Connecting Overview

MySQL | PostgreSQL | SQL Server

This page provides a summary of options for connecting to your Cloud SQL instance.

Introduction

Using the Cloud SQL Auth proxy is the recommended method for connecting to a Cloud SQL instance. The Cloud SQL Auth proxy:

Works with both public and private IP endpoints
Validates connections using credentials for a user or service account
Wraps the connection in a SSL/TLS layer that is authorized for a Cloud SQL instance

Some Google Cloud services and applications provide connections for public IP paths with encryption and authorization using the Cloud SQL Auth proxy, including:

For private IP paths, these services and applications connect directly to your instance through Serverless VPC Access.

Applications running in Google Kubernetes Engine can connect using the Cloud SQL Auth proxy.

See the Quickstart for using the Cloud SQL Auth proxy for a basic introduction to its usage.

You can also connect, with or without the Cloud SQL Auth proxy, using a mysql client from a local machine or Compute Engine.

Overview

When considering how to connect to your Cloud SQL instance, there are many choices to keep in mind, including:

Do you want your Cloud SQL instance to be accessible from the internet, or kept private within a virtual private cloud (VPC) network?
Are you planning to write your own connection code, or connect using publicly available tools such as the Cloud SQL Auth proxy or a mysql client?
Do you want to require encryption through SSL/TLS or allow unencrypted traffic?

In the sections below, we discuss the options Cloud SQL provides for connecting, authorizing, and authenticating to your database.

How to connect - which network path you use to reach your instance:
- An internal, VPC-only (Private) IP address.
- An external, internet-accessible (Public) IP address.

How to authorize - which connections are authorized and allowed to connect to your Cloud SQL instance:
- Cloud SQL Auth proxy and Cloud SQL language connectors - these provide access based on IAM.
- Self-managed SSL/TLS certificates - these only allow connections based on specific public keys.
- Authorized networks - a list of IP addresses allowed to connect.

How to authenticate - the method to login to your database.
- Native database authentication - login with a username/password set in the database engine.

Use the information below to decide which connection, authorization and authentication options work best for you.

Before you start

Granting access to an application does not automatically enable a database user account to connect to the instance. Before you can connect to an instance, you must have a database user account you can connect with. For new instances, this means you must have configured the default user account. Learn more.

Connection options

Private IP

A private IP is an IPv4 or IPv6 address that is accessible on a Virtual Private Cloud (VPC).

Security considerations

You can use this address to connect from other resources with access to the VPC; connections over private IP typically provide lower latency and limited attack vectors, as they don't require traversing the internet. Optionally, you can require all connections use either the Cloud SQL proxy or self-managed SSL certificates.

Recommended use case

Configuring your instance with a private IP is preferred when connecting from a client on a resource with access to a VPC. For more information about what resources can use private IP, see Requirements for Private IP.

Learn more

Learn more about using private IP with Cloud SQL

For instructions on adding a private IP to your instance, see Configuring Private IP Connectivity.

Public IP

A public IP is an IPv4 or IPv6 address that is available externally on the public internet. This address can receive connections from devices both inside and outside of Google's network, including from locations like your home or office.

Security considerations

In order to help keep your instance secure, any connections to a Cloud SQL instance using a public IP must be authorized using either the Cloud SQL Auth proxy or authorized networks.

Recommended use case

Configuring your instance with a public IP is best when connecting from a client that doesn't meet the requirements for a VPC.

Learn more

For instructions about adding a public IP to your instance, see Configuring Public IP Connectivity.

Authorization options

Cloud SQL connectors

Security considerations

The Cloud SQL Auth proxy allows you to authorize and secure your connections using Identity and Access Management (IAM) permissions. The Cloud SQL Auth proxy validates connections using credentials for a user or service account, and wrapping the connection in a SSL/TLS layer that is authorized for a Cloud SQL instance. For more details about how the Cloud SQL Auth proxy works, see About the Cloud SQL Auth proxy.

Recommended use case

Using the Cloud SQL Auth proxy is the recommended method for authenticating connections to a Cloud SQL instance, as it is the most secure method.

The Cloud SQL Auth proxy is an open source library distributed as an executable binary. The Cloud SQL Auth proxy acts as an intermediary server that listens for incoming connections, wraps them in SSL/TLS, and then passes them to a Cloud SQL instance.

Additionally, some languages have the option of using a client library. You can use these libraries directly from the language environment; they provide the same authentication as the Cloud SQL Auth proxy without requiring an external process. To get started, see Connecting using the Cloud SQL Connectors.

Some environments provide a mechanism that connects using the Cloud SQL Auth proxy. For instructions about connecting using these environments, see one of the following:

Self-managed SSL/TLS certificates

Instead of using the Cloud SQL Auth proxy to encrypt your connections, it is possible to set up client/server SSL/TLS certificates that are specific to a Cloud SQL instance. These certificates are used to both validate the client and server to each other and encrypt connections between them.

It is strongly recommended to use self-managed SSL/TLS certificates to provide encryption when not using the Cloud SQL Auth proxy. Failing to do so means your data is being transmitted insecurely, and may be intercepted or inspected by a third-party.

To get started with self-managed SSL/TLS certificates, see Authorizing with SSL/TLS certificates.

Authorized networks

Unless using the Cloud SQL Auth proxy, connections to the public IP address of an instance are only allowed if the connection come from from an authorized network. Authorized networks are IP addresses or ranges that the user has specified as having permission to connect.

To get started with authorized networks, see Authorizing with Authorized Networks.

Managing database connections

Database connections consume resources on the server and the connecting application. Always use good connection management practices to minimize your application's footprint and reduce the likelihood of exceeding Cloud SQL connection limits. For more information, see Managing database connections.

Authentication options

Authentication provides access control by verifying the identity of a user. For end users, authentication is achieved when the user enters credentials (a username and password). For applications, authentication is achieved when a user's credentials are assigned to a service account.

Cloud SQL uses the database's built-in authentication that authenticates using a username and password. For more information, see creating and managing MySQL users.

Tools for connecting

The following table contains some options for connecting to Cloud SQL:

Connection option	More information
Cloud SQL Auth proxy	About the Cloud SQL Auth proxy Connecting using the Cloud SQL Auth proxy Connecting using the Cloud SQL Auth proxy Docker Image
gcloud	`gcloud sql connect`
Cloud SQL language connectors	Connect using Cloud SQL connectors for Java, Python and Go.
Cloud Shell	Connecting using the Cloud Shell
Apps Script	External connections with Apps Script Apps Script sample GitHub page

Connect using third-party database administration tools
MySQL Workbench	Connecting with MySQL Workbench
Toad for MySQL	Connecting with Toad for MySQL
SQuirrel SQL	Connecting with SQuirrel SQL
phpAdmin	Using phpMyAdmin with Cloud SQL on App Engine

Connecting applications with dynamically-assigned IP addresses

Some applications need to connect to your Cloud SQL instance using a dynamically assigned, or ephemeral, IP address. This is the case for Platform as a Service (Paas) applications, among others.

The best solution for these applications is to connect by using the Cloud SQL Auth proxy. This solution provides the best access control for your instance.

Code samples

You can connect to the Cloud SQL Auth proxy from any language that enables you to connect to a Unix or TCP socket. Below are some code snippets from complete examples on GitHub to help you understand how they work together in your application.

Connecting with TCP

Cloud SQL Auth proxy invocation statement:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306 &

Python

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

cloud-sql/mysql/sqlalchemy/main.py

View on GitHub

# Remember - storing secrets in plaintext is potentially unsafe. Consider using
# something like https://cloud.google.com/secret-manager/docs/overview to help keep
# secrets secret.
db_user = os.environ["DB_USER"]
db_pass = os.environ["DB_PASS"]
db_name = os.environ["DB_NAME"]
db_host = os.environ["DB_HOST"]

# Extract host and port from db_host
host_args = db_host.split(":")
db_hostname, db_port = host_args[0], int(host_args[1])

pool = sqlalchemy.create_engine(
    # Equivalent URL:
    # mysql+pymysql://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
    sqlalchemy.engine.url.URL.create(
        drivername="mysql+pymysql",
        username=db_user,  # e.g. "my-database-user"
        password=db_pass,  # e.g. "my-database-password"
        host=db_hostname,  # e.g. "127.0.0.1"
        port=db_port,  # e.g. 3306
        database=db_name,  # e.g. "my-database-name"
    ),
    **db_config
)

Java

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

Note:

CLOUD_SQL_CONNECTION_NAME should be represented as <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
Using the argument ipTypes=PRIVATE will force the SocketFactory to connect with an instance's associated private IP
See the JDBC socket factory version requirements for the pom.xml file here .

cloud-sql/mysql/servlet/src/main/java/com/example/cloudsql/ConnectionPoolContextListener.java

View 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 URL is equivalent to setting the config options below:
// jdbc:mysql:///<DB_NAME>?cloudSqlInstance=<CLOUD_SQL_CONNECTION_NAME>&
// socketFactory=com.google.cloud.sql.mysql.SocketFactory&user=<DB_USER>&password=<DB_PASS>
// 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.setJdbcUrl(String.format("jdbc:mysql:///%s", DB_NAME));
config.setUsername(DB_USER); // e.g. "root", "mysql"
config.setPassword(DB_PASS); // e.g. "my-password"

config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.mysql.SocketFactory");
config.addDataSourceProperty("cloudSqlInstance", CLOUD_SQL_CONNECTION_NAME);

// The ipTypes argument can be used to specify a comma delimited list of preferred IP types 
// for connecting to a Cloud SQL instance. The argument ipTypes=PRIVATE will force the 
// SocketFactory to connect with an instance's associated private IP. 
config.addDataSourceProperty("ipTypes", "PUBLIC,PRIVATE");

// ... Specify additional connection properties here.
// ...

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

Node.js

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

cloud-sql/mysql/mysql/server.js

View on GitHub

const createTcpPool = async config => {
  // Extract host and port from socket address
  const dbSocketAddr = process.env.DB_HOST.split(':');

  // Establish a connection to the database
  return await mysql.createPool({
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    host: dbSocketAddr[0], // e.g. '127.0.0.1'
    port: dbSocketAddr[1], // e.g. '3306'
    // ... Specify additional properties here.
    ...config,
  });
};

Go

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

cloudsql/mysql/database-sql/cloudsql.go

View on GitHub

var (
	dbUser    = mustGetenv("DB_USER") // e.g. 'my-db-user'
	dbPwd     = mustGetenv("DB_PASS") // e.g. 'my-db-password'
	dbTCPHost = mustGetenv("DB_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
	dbPort    = mustGetenv("DB_PORT") // e.g. '3306'
	dbName    = mustGetenv("DB_NAME") // e.g. 'my-database'
)

var dbURI string
dbURI = fmt.Sprintf("%s:%s@tcp(%s:%s)/%s?parseTime=true", dbUser, dbPwd, dbTCPHost, dbPort, dbName)

// dbPool is the pool of database connections.
dbPool, err := sql.Open("mysql", dbURI)
if err != nil {
	return nil, fmt.Errorf("sql.Open: %v", err)
}

// ...

return dbPool, nil

C#

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

cloud-sql/mysql/Startup.cs

View on GitHub

            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<DB_HOST>;Database=<DB_NAME>;"
            var connectionString = new MySqlConnectionStringBuilder()
            {
                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = MySqlSslMode.None,

                // Remember - storing secrets in plain text is potentially unsafe. Consider using
                // something like https://cloud.google.com/secret-manager/docs/overview to help keep
                // secrets secret.
                Server = Environment.GetEnvironmentVariable("DB_HOST"),   // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                UserID = Environment.GetEnvironmentVariable("DB_USER"),   // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;

Ruby

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

cloud-sql/mysql/activerecord/config/database.yml

View on GitHub

development:
  adapter: mysql2
  # Configure additional properties here
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: "<%= ENV.fetch("DB_HOST") { "127.0.0.1" }%>" # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 3306 }%>
  socket: "<%= ENV.fetch("DB_SOCKET_DIR") { '/cloudsql' } %>/<%= ENV["INSTANCE_CONNECTION_NAME"] %>"

PHP

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

cloud_sql/mysql/pdo/src/DBInitializer.php

View on GitHub

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

// Connect using TCP
$dsn = sprintf('mysql:dbname=%s;host=%s', $dbName, $dbHost);

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);

Connecting with Unix sockets

Cloud SQL Auth proxy invocation statement:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME -dir=/cloudsql &

Python

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

cloud-sql/mysql/sqlalchemy/main.py

View on GitHub

# Remember - storing secrets in plaintext is potentially unsafe. Consider using
# something like https://cloud.google.com/secret-manager/docs/overview to help keep
# secrets secret.
db_user = os.environ["DB_USER"]
db_pass = os.environ["DB_PASS"]
db_name = os.environ["DB_NAME"]
db_socket_dir = os.environ.get("DB_SOCKET_DIR", "/cloudsql")
cloud_sql_connection_name = os.environ["CLOUD_SQL_CONNECTION_NAME"]

pool = sqlalchemy.create_engine(
    # Equivalent URL:
    # mysql+pymysql://<db_user>:<db_pass>@/<db_name>?unix_socket=<socket_path>/<cloud_sql_instance_name>
    sqlalchemy.engine.url.URL.create(
        drivername="mysql+pymysql",
        username=db_user,  # e.g. "my-database-user"
        password=db_pass,  # e.g. "my-database-password"
        database=db_name,  # e.g. "my-database-name"
        query={
            "unix_socket": "{}/{}".format(
                db_socket_dir,  # e.g. "/cloudsql"
                cloud_sql_connection_name)  # i.e "<PROJECT-NAME>:<INSTANCE-REGION>:<INSTANCE-NAME>"
        }
    ),
    **db_config
)

Java

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

cloud-sql/mysql/servlet/src/main/java/com/example/cloudsql/ConnectionPoolContextListener.java

View 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 URL is equivalent to setting the config options below:
// jdbc:mysql:///<DB_NAME>?cloudSqlInstance=<CLOUD_SQL_CONNECTION_NAME>&
// socketFactory=com.google.cloud.sql.mysql.SocketFactory&user=<DB_USER>&password=<DB_PASS>
// 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.setJdbcUrl(String.format("jdbc:mysql:///%s", DB_NAME));
config.setUsername(DB_USER); // e.g. "root", "mysql"
config.setPassword(DB_PASS); // e.g. "my-password"

config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.mysql.SocketFactory");
config.addDataSourceProperty("cloudSqlInstance", CLOUD_SQL_CONNECTION_NAME);

// The ipTypes argument can be used to specify a comma delimited list of preferred IP types 
// for connecting to a Cloud SQL instance. The argument ipTypes=PRIVATE will force the 
// SocketFactory to connect with an instance's associated private IP. 
config.addDataSourceProperty("ipTypes", "PUBLIC,PRIVATE");

// ... Specify additional connection properties here.
// ...

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

Node.js

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

cloud-sql/mysql/mysql/server.js

View on GitHub

const createUnixSocketPool = async config => {
  const dbSocketPath = process.env.DB_SOCKET_PATH || '/cloudsql';

  // Establish a connection to the database
  return await mysql.createPool({
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    // If connecting via unix domain socket, specify the path
    socketPath: `${dbSocketPath}/${process.env.CLOUD_SQL_CONNECTION_NAME}`,
    // Specify additional properties here.
    ...config,
  });
};

C#

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

cloud-sql/mysql/Startup.cs

View on GitHub

// Equivalent connection string:
// "Server=<dbSocketDir>/<INSTANCE_CONNECTION_NAME>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>;Protocol=unix"
String dbSocketDir = Environment.GetEnvironmentVariable("DB_SOCKET_PATH") ?? "/cloudsql";
String instanceConnectionName = Environment.GetEnvironmentVariable("INSTANCE_CONNECTION_NAME");
var connectionString = new MySqlConnectionStringBuilder()
{
    // The Cloud SQL proxy provides encryption between the proxy and instance.
    SslMode = MySqlSslMode.None,
    // Remember - storing secrets in plain text is potentially unsafe. Consider using
    // something like https://cloud.google.com/secret-manager/docs/overview to help keep
    // secrets secret.
    Server = String.Format("{0}/{1}", dbSocketDir, instanceConnectionName),
    UserID = Environment.GetEnvironmentVariable("DB_USER"),   // e.g. 'my-db-user
    Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
    Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'
    ConnectionProtocol = MySqlConnectionProtocol.UnixSocket
};
connectionString.Pooling = true;
// Specify additional properties here.
return connectionString;

Go

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

cloudsql/mysql/database-sql/cloudsql.go

View on GitHub

var (
	dbUser                 = mustGetenv("DB_USER")                  // e.g. 'my-db-user'
	dbPwd                  = mustGetenv("DB_PASS")                  // e.g. 'my-db-password'
	instanceConnectionName = mustGetenv("INSTANCE_CONNECTION_NAME") // e.g. 'project:region:instance'
	dbName                 = mustGetenv("DB_NAME")                  // e.g. 'my-database'
)

socketDir, isSet := os.LookupEnv("DB_SOCKET_DIR")
if !isSet {
	socketDir = "/cloudsql"
}

var dbURI string
dbURI = fmt.Sprintf("%s:%s@unix(/%s/%s)/%s?parseTime=true", dbUser, dbPwd, socketDir, instanceConnectionName, dbName)

// dbPool is the pool of database connections.
dbPool, err := sql.Open("mysql", dbURI)
if err != nil {
	return nil, fmt.Errorf("sql.Open: %v", err)
}

// ...

return dbPool, nil

Ruby

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

cloud-sql/mysql/activerecord/config/database.yml

View on GitHub

production:
  adapter: mysql2
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_production" } %>
  socket: "<%= ENV.fetch("DB_SOCKET_DIR") { '/cloudsql' } %>/<%= ENV["INSTANCE_CONNECTION_NAME"] %>"

PHP

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

cloud_sql/mysql/pdo/src/DBInitializer.php

View on GitHub

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $connectionName = getenv("CLOUD_SQL_CONNECTION_NAME");
// $socketDir = getenv('DB_SOCKET_DIR') ?: '/cloudsql';

// Connect using UNIX sockets
$dsn = sprintf(
    'mysql:dbname=%s;unix_socket=%s/%s',
    $dbName,
    $socketDir,
    $connectionName
);

// Connect to the database.
$conn = new PDO($dsn, $username, $password, $conn_config);

Troubleshooting

If you are having problems connecting, check the following pages for help debugging or finding solutions to known issues:

What's next

Learn how to connect with the Quickstart for Cloud SQL for mysql.
Learn best practices for managing database connections.
Learn about IAM database authentication.
Learn about connecting using a mysql client from a local machine or Compute Engine.
Learn about configuring IP connectivity.
Learn about connecting with other MySQL tools.
Learn about MySQL connectors.
Learn about the Cloud SQL Auth proxy.
Learn about options for support.