The Google Cloud SQL Python Connector is a client library that helps connect Python applications to Google Cloud SQL databases. It automatically handles authentication, encryption, and secure connection management, acting as a smart proxy for your database connections. As of version 1.20.1, it provides robust and secure connectivity. The library is actively maintained by Google, with frequent updates aligning with Cloud SQL proxy and client library best practices.
pip install cloud-sql-python-connector[pymysql]Verified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates connecting to a MySQL Cloud SQL instance using PyMySQL. It relies on environment variables for sensitive information and the instance connection name. Ensure you have the `cloud-sql-python-connector[pymysql]` package installed. The connector automatically handles authentication using Application Default Credentials (ADC) or a service account key specified by `GOOGLE_APPLICATION_CREDENTIALS`.
Update your code to use `connector.connect(instance_connection_name, dbapi_module, ...)` and ensure you pass the DBAPI module (e.g., `pymysql`) as the second argument.
Remove the `refresh_delay` parameter and its value from your `Connector` constructor calls. The library will manage token refreshes automatically.
Install the connector with the correct extra: `pip install cloud-sql-python-connector[<driver>]`. For example, `pip install cloud-sql-python-connector[pymysql]`.
Always provide the full instance connection name in `PROJECT_ID:REGION:INSTANCE_NAME` format, typically retrieved from the Cloud SQL instance details in the Google Cloud Console.
Set up Application Default Credentials by following the instructions at https://cloud.google.com/docs/authentication/external/set-up-adc. This often involves running `gcloud auth application-default login` or setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
Ensure your environment is authenticated with Google Cloud, typically by setting up Application Default Credentials (ADC). This can be done by running `gcloud auth application-default login` if using the Google Cloud SDK, or by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of a service account key file.
Ensure the `cloud-sql-python-connector` package is installed with its required database driver. For example, for MySQL: `pip install "cloud-sql-python-connector[pymysql]"`. For PostgreSQL: `pip install "cloud-sql-python-connector[pg8000]"` or `pip install "cloud-sql-python-connector[asyncpg]"`. Make sure this is included in your `requirements.txt` if deploying.
Verify the database username and password are correct for the SQL user. If using IAM authentication, ensure the service account or user has the `Cloud SQL Client` IAM role on the Google Cloud Project and is added as an IAM database user on the Cloud SQL instance.
Ensure the Cloud SQL Auth Proxy is running and correctly creating the Unix socket for your instance. Verify that the `instance_connection_name` (e.g., `project-id:region:instance-name`) in your application's connection string or environment variables (e.g., `CLOUD_SQL_INSTANCE_CONNECTION_NAME`) is exact. On platforms like App Engine Flex, ensure `cloud_sql_instances` is configured in `app.yaml`.
Correct the package name to `cloud-sql-python-connector` in your `pip install` command or `requirements.txt`. For example, `pip install "cloud-sql-python-connector[DRIVER]"`. If using a slim Docker image (like Alpine), consider switching to a Debian-based image or explicitly installing build dependencies.