Connecting using the Cloud SQL connectors

The Cloud SQL connectors are libraries that provide encryption and IAM-based authorization when connecting to a Cloud SQL instance. They can't provide a network path to a Cloud SQL instance if one is not already present.

Other ways to connect to a Cloud SQL instance include using a database client or the Cloud SQL Auth proxy. See the Connecting Overview page for more information on connecting to a Cloud SQL instance.

This page discusses the following Cloud SQL connectors:

  • The Cloud SQL Java connector
  • The Cloud SQL Python connector

Before you begin

Setup

Java

The Cloud SQL Java connector is a library that provides IAM-based authorization and encryption when connecting to a Cloud SQL instance. It can not provide a network path to a Cloud SQL instance if one is not already present.

Installation

For instructions on building and using the drivers for JDBC and R2DBC with the Cloud SQL Java connector, see the following links:

JDBC: Connecting to SQL Server using JDBC.

R2DBC: Connecting to SQL Server using R2DBC.

For examples of this library being used in the context of an application, check out these sample applications.

Authentication

This library uses Application Default Credentials to authenticate the connection to the Cloud SQL server.

To activate credentials locally, use the following gcloud command:

    gcloud auth application-default login
    

Connect with Intellij

In order to connect IntelliJ to your Cloud SQL instance, you will need to add the library as a jar with dependencies in the Additional Files section on the driver settings page. For example, prebuilt fat jars can be found on the Cloud SQL Java connector Releases page for this purpose.

Python

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.

The currently supported driver for SQL Server is pytds .

Installation

To install the latest release, follow these instructions.

Authentication

This library uses Application Default Credentials to authenticate the connection to the Cloud SQL server.

To activate credentials locally, use the following gcloud command:

    gcloud auth application-default login
    

Usage

Java

To see this snippet in the context of a web application, view the README on GitHub.

// Note: For Java users, the Cloud SQL JDBC Socket Factory can provide authenticated connections
// which is preferred to using the Cloud SQL Proxy with Unix sockets.
// See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.

// The configuration object specifies behaviors for the connection pool.
HikariConfig config = new HikariConfig();

// The following is equivalent to setting the config options below:
// jdbc:sqlserver://;user=<DB_USER>;password=<DB_PASS>;databaseName=<DB_NAME>;
// socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;
// socketFactoryConstructorArg=<INSTANCE_CONNECTION_NAME>

// See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
// https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

// Configure which instance and what database user to connect with.
config
    .setDataSourceClassName("com.microsoft.sqlserver.jdbc.SQLServerDataSource");
config.setUsername(DB_USER); // e.g. "root", "sqlserver"
config.setPassword(DB_PASS); // e.g. "my-password"
config.addDataSourceProperty("databaseName", DB_NAME);

config.addDataSourceProperty("socketFactoryClass",
    "com.google.cloud.sql.sqlserver.SocketFactory");
config.addDataSourceProperty("socketFactoryConstructorArg", INSTANCE_CONNECTION_NAME);

// ... Specify additional connection properties here.

// ...

// Initialize the connection pool using the configuration object.
DataSource pool = new HikariDataSource(config);

Python

See How to use the connector for detailed instructions on using the library. View example connection test code on GitHub.

# The Cloud SQL Python Connector can be used along with SQLAlchemy using the
# 'creator' argument to 'create_engine'. To use SQLAlchemy with pytds, include
# 'sqlalchemy-pytds` in your dependencies
def init_connection_engine() -> sqlalchemy.engine.Engine:
    def getconn() -> pytds.Connection:
        conn = connector.connect(
            os.environ["SQLSERVER_CONNECTION_NAME"],
            "pytds",
            user=os.environ["SQLSERVER_USER"],
            password=os.environ["SQLSERVER_PASS"],
            db=os.environ["SQLSERVER_DB"],
        )
        return conn

    engine = sqlalchemy.create_engine(
        "mssql+pytds://localhost",
        creator=getconn,
    )
    engine.dialect.description_encoding = None
    return engine

Troubleshooting

Driver versions

Make sure you are using the latest version of the Cloud SQL connectors and your database driver to avoid incompatibilities. Some older versions of drivers are not supported

Connection paths

The Cloud SQL connectors provide authorization for connections, but they don't provide new paths to connectivity. For example, in order to connect to a Cloud SQL instance using a Private IP address, your application must already have VPC access. In order to connect to a Cloud SQL instance using a Public IP address, your application must be in an authorized network.

Debugging connection issues

For additional help with connection issues, see the Troubleshooting and Debugging connection issues pages.

What's next