Cloud SQL Connector for Python Drivers

Warning: This project is currently in beta. Please open an issue if you would like to report a bug or documentation issue, request a feature, or have a question.

The Cloud SQL Python Connector is a library that can be used alongside a database driver to allow users with sufficient permissions to connect to a Cloud SQL database without having to manually allowlist IPs or manage SSL certificates.

Currently supported drivers are

• pymysql (MySQL)
• pg8000 (PostgreSQL)
• pytds (SQL Server)

Supported Python Versions

Currently Python versions >= 3.6 are supported.

Authentication

This library uses the Application Default Credentials to authenticate the connection to the Cloud SQL server. For more details, see the previously mentioned link.

To activate credentials locally, use the following gcloud command:

gcloud auth application-default login

How to install this connector

Install latest release from PyPI

Upgrade to the latest version of pip, then run the following command, replacing driver with one of the driver names listed above.

pip install cloud-sql-python-connector[driver]

For example, to use the Python connector with pymysql, run pip install cloud-sql-python-connector[pymysql]

Install dev version

Clone this repo, cd into the cloud-sql-python-connector directory then run the following command to install the package:

pip install .

Conversely, install straight from Github using pip:

pip install git+https://github.com/GoogleCloudPlatform/cloud-sql-python-connector

How to use this connector

To use the connector: import the connector and SQLAlchemy by including the following statements at the top of your Python file:

from google.cloud.sql.connector import connector
import sqlalchemy

The connector itself creates connection objects by calling its connect method but does not manage database connection pooling. For this reason, it is recommended to use the connector alongside a library that can create connection pools, such as SQLAlchemy. This will allow for connections to remain open and be reused, reducing connection overhead and the number of connections needed.

In the connector's connect method below, input your connection string as the first positional argument and the name of the database driver for the second positional argument. Insert the rest of your connection keyword arguments like user, password and database. You can also set the optional timeout or ip_type keyword arguments.

To use this connector with SQLAlchemy, use the creator argument for sqlalchemy.create_engine:

def getconn() -> pymysql.connections.Connection:
    conn: pymysql.connections.Connection = connector.connect(
        "project:region:instance",
        "pymysql",
        user="root",
        password="shhh",
        db="your-db-name"
    )
    return conn

pool = sqlalchemy.create_engine(
    "mysql+pymysql://",
    creator=getconn,
)

The returned connection pool engine can then be used to query and modify the database.

# insert statement
insert_stmt = sqlalchemy.text(
    "INSERT INTO my_table (id, title) VALUES (:id, :title)",
)

with pool.connect() as db_conn:
    # insert into database
    db_conn.execute(insert_stmt, id="book1", title="Book One")

    # query database
    result = db_conn.execute("SELECT * from my_table").fetchall()

    # Do something with the results
    for row in result:
        print(row)

Note: For more examples of using SQLAlchemy to manage connection pooling with the connector, please see Cloud SQL SQLAlchemy Samples.

Note for SQL Server users: If your SQL Server instance requires SSL, you need to download the CA certificate for your instance and include cafile={path to downloaded certificate} and validate_host=False. This is a workaround for a known issue.

Specifying Public or Private IP

The Cloud SQL Connector for Python can be used to connect to Cloud SQL instances using both public and private IP addresses. To specify which IP address to use to connect, set the ip_type keyword argument Possible values are IPTypes.PUBLIC and IPTypes.PRIVATE. Example:

connector.connect(
    "project:region:instance",
    "pymysql",
    ip_types=IPTypes.PRIVATE # Prefer private IP
... insert other kwargs ...
)

Note: If specifying Private IP, your application must already be in the same VPC network as your Cloud SQL Instance.

IAM Authentication

Connections using Automatic IAM database authentication are supported when using the Postgres driver. This feature is unsupported for other drivers. If automatic IAM authentication is not supported for your driver, you can use Manual IAM database authentication to connect. First, make sure to configure your Cloud SQL Instance to allow IAM authentication and add an IAM database user. Now, you can connect using user or service account credentials instead of a password. In the call to connect, set the enable_iam_auth keyword argument to true and user to the email address associated with your IAM user. Example:

connector.connect(
     "project:region:instance",
     "pg8000",
     user="postgres-iam-user@gmail.com",
     db="my_database",
     enable_iam_auth=True,
 )

SQL Server Active Directory Authentication

Active Directory authentication for SQL Server instances is currently only supported on Windows. First, make sure to follow these steps to set up a Managed AD domain and join your Cloud SQL instance to the domain. See here for more info on Cloud SQL Active Directory integration.

Once you have followed the steps linked above, you can run the following code to return a connection object:

connector.connect(
    "project:region:instance",
    "pytds",
    db="my_database",
    active_directory_auth=True,
    server_name="public.[instance].[location].[project].cloudsql.[domain]",
)

Or, if using Private IP:

connector.connect(
    "project:region:instance",
    "pytds",
    db="my_database",
    active_directory_auth=True,
    server_name="private.[instance].[location].[project].cloudsql.[domain]",
    ip_types=IPTypes.PRIVATE
)

Support policy

Major version lifecycle

This project uses semantic versioning, and uses the following lifecycle regarding support for a major version:

Active - Active versions get all new features and security fixes (that wouldn’t otherwise introduce a breaking change). New major versions are guaranteed to be "active" for a minimum of 1 year. Deprecated - Deprecated versions continue to receive security and critical bug fixes, but do not receive new features. Deprecated versions will be publicly supported for 1 year. Unsupported - Any major version that has been deprecated for >=1 year is considered publicly unsupported.

Release cadence

This project aims for a minimum monthly release cadence. If no new features or fixes have been added, a new PATCH version with the latest dependencies is released.

Contributing

We welcome outside contributions. Please see our Contributing Guide for details on how best to contribute.