{"id":1422,"library":"cloud-sql-python-connector","title":"Google Cloud SQL Python Connector","description":"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.","status":"active","version":"1.20.1","language":"en","source_language":"en","source_url":"https://github.com/GoogleCloudPlatform/cloud-sql-python-connector","tags":["google-cloud","sql","database","connector","mysql","postgresql"],"install":[{"cmd":"pip install cloud-sql-python-connector[pymysql]","lang":"bash","label":"For MySQL using PyMySQL"},{"cmd":"pip install cloud-sql-python-connector[pg8000]","lang":"bash","label":"For PostgreSQL using pg8000"},{"cmd":"pip install cloud-sql-python-connector[psycopg2]","lang":"bash","label":"For PostgreSQL using psycopg2"}],"dependencies":[{"reason":"Required for connecting to MySQL databases via a connector extra.","package":"pymysql","optional":true},{"reason":"Required for connecting to PostgreSQL databases via a connector extra.","package":"pg8000","optional":true},{"reason":"Required for connecting to PostgreSQL databases via a connector extra (psycopg2-binary is commonly used for ease of installation).","package":"psycopg2-binary","optional":true}],"imports":[{"symbol":"Connector","correct":"from google.cloud.sql.connector import Connector"},{"symbol":"IPTypes","correct":"from google.cloud.sql.connector import IPTypes"}],"quickstart":{"code":"import os\nimport pymysql\nfrom google.cloud.sql.connector import Connector, IPTypes\n\n# Recommended: Use Application Default Credentials (ADC).\n# Ensure GOOGLE_APPLICATION_CREDENTIALS env var is set or ADC is configured.\n\n# Initialize Connector\nconnector = Connector()\n\n# Function to get a database connection\ndef get_db_connection():\n    try:\n        conn = connector.connect(\n            os.environ.get(\"INSTANCE_CONNECTION_NAME\", \"your-project:your-region:your-instance\"),\n            \"pymysql\", # Specify the DBAPI module you are using\n            user=os.environ.get(\"DB_USER\", \"root\"),\n            password=os.environ.get(\"DB_PASS\", \"\"),\n            db=os.environ.get(\"DB_NAME\", \"my_database\"),\n            ip_type=IPTypes.PUBLIC if os.environ.get(\"IP_TYPE\", \"public\").lower() == \"public\" else IPTypes.PRIVATE\n        )\n        return conn\n    except Exception as e:\n        print(f\"Error creating database connection: {e}\")\n        return None\n\n# Example Usage:\nif __name__ == \"__main__\":\n    # Set environment variables for testing, or rely on actual deployment configs.\n    # os.environ['INSTANCE_CONNECTION_NAME'] = 'your-project:your-region:your-instance'\n    # os.environ['DB_USER'] = 'my_user'\n    # os.environ['DB_PASS'] = 'my_password'\n    # os.environ['DB_NAME'] = 'my_database'\n    # os.environ['IP_TYPE'] = 'public' # or 'private'\n\n    conn = None\n    try:\n        conn = get_db_connection()\n        if conn:\n            with conn.cursor() as cursor:\n                cursor.execute(\"SELECT 1 + 1 AS solution;\")\n                result = cursor.fetchone()\n                print(f\"Database connection successful! Result: {result}\")\n    except Exception as e:\n        print(f\"An error occurred during database operation: {e}\")\n    finally:\n        if conn:\n            conn.close()\n        connector.close() # Important: close the connector when your application exits","lang":"python","description":"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`."},"warnings":[{"fix":"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.","message":"Major breaking changes occurred in version 1.0.0. The primary connection method was renamed from `create_connection` to `connect`, and the `database_driver` argument was removed in favor of passing the DBAPI module object (e.g., `pymysql`) directly.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Remove the `refresh_delay` parameter and its value from your `Connector` constructor calls. The library will manage token refreshes automatically.","message":"The `refresh_delay` parameter in the `Connector` constructor was removed, as its functionality is now handled internally and dynamically by the library.","severity":"breaking","affected_versions":">=1.15.0"},{"fix":"Install the connector with the correct extra: `pip install cloud-sql-python-connector[<driver>]`. For example, `pip install cloud-sql-python-connector[pymysql]`.","message":"You must install the appropriate database driver extra (e.g., `[pymysql]`, `[pg8000]`, `[psycopg2]`) when installing the connector, otherwise, connection attempts will fail with module not found errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"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.","message":"Incorrect `instance_connection_name` format. The correct format is `PROJECT_ID:REGION:INSTANCE_NAME`. Using just `INSTANCE_NAME` or other variations will lead to connection failures.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}