Connecting using the Cloud SQL Auth proxy

MySQL | PostgreSQL | SQL Server

This page describes how to connect to your Cloud SQL instance using the Cloud SQL Auth proxy.

For information about connecting a psql client to a Cloud SQL instance using public IP, see Connecting using a database client.

For more information about how the Cloud SQL Auth proxy works, see About the Cloud SQL Auth proxy.

Before you begin

Before you can connect to a Cloud SQL instance, do the following:

Enable the Cloud SQL Admin API.
Enable the API
Create a Cloud SQL instance, including configuring the default user.

For more information about creating instances, see Creating Instances.

For more information about configuring the default user, see Configuring the default user account.
Install and initialize the Cloud SDK.
Optional. Install the Cloud SQL Auth proxy Docker client.

Options for authenticating the Cloud SQL Auth proxy

All of these options use an INSTANCE_CONNECTION_NAME as the connection string to identify a Cloud SQL instance. You can find the INSTANCE_CONNECTION_NAME on the Overview page for your instance in the Google Cloud Console. or by running the following command:

gcloud sql instances describe INSTANCE_NAME --project PROJECT_ID.

For example: gcloud sql instances describe myinstance --project myproject.

Some of these options use a JSON credentials file that includes the RSA private key for the account. For instructions on creating a JSON credentials file for a service account, see Creating a service account.

The Cloud SQL Auth proxy provides several alternatives for authentication, depending on your environment. The Cloud SQL Auth proxy checks for each of the following items, in the following order, using the first one it finds to attempt to authenticate:

Credentials supplied by the credential_file flag.
Use a service account to create and download the associated JSON file, and set the -credential_file flag to the path of the file when you start the Cloud SQL Auth proxy. The service account must have the required permissions for the Cloud SQL instance.
To use this option on the command-line, invoke the cloud_sql_proxy command with the -credential_file flag set to the path and filename of a JSON credential file. The path can be absolute, or relative to the current working directory. For example:
```
./cloud_sql_proxy -credential_file=PATH_TO_KEY_FILE -instances=INSTANCE_CONNECTION_NAME
  
```
For detailed instructions about adding IAM roles to a service account, see Granting Roles to Service Accounts.
For more information about the roles Cloud SQL supports, see Project access control for Cloud SQL.
Credentials supplied by an access token.
Create an access token and invoke the cloud_sql_proxy command with the -token flag set to an OAuth 2.0 access token. For example:
```
./cloud_sql_proxy -token=ACCESS_TOKEN -instances=INSTANCE_CONNECTION_NAME
  
```
Credentials supplied by an environment variable.
This option is similar to using the -credential_file flag, except you specify the JSON credential file you set in the GOOGLE_APPLICATION_CREDENTIALS environment variable instead of using the -credential_file command-line argument.
Credentials from an authenticated Cloud SDK client.
If you have installed the cloud command-line tool and have authenticated with your personal account, the Cloud SQL Auth proxy can use the same account credentials. This method is especially helpful for getting a development environment up and running.
To enable the Cloud SQL Auth proxy to use your Cloud SDK credentials, use the gcloud auth login command to authenticate the Cloud SDK.
You can determine what your current Cloud SDK credentials are by using the gcloud auth list command.

If no account was selected for gcloud auth login, the Cloud SQL Auth proxy checks for an account that was selected for gcloud auth application-default login.
Credentials associated with the Compute Engine instance.
If you are connecting to Cloud SQL from a Compute Engine instance, the Cloud SQL Auth proxy can use the service account associated with the Compute Engine instance. If the service account has the required permissions for the Cloud SQL instance, the Cloud SQL Auth proxy authenticates successfully.
If the Compute Engine instance is in the same project as the Cloud SQL instance, the default service account for the Compute Engine instance has the necessary permissions for authenticating the Cloud SQL Auth proxy. If the two instances are in different projects, you must add the Compute Engine instance's service account to the project containing the Cloud SQL instance.
Environment's default service account
If the Cloud SQL Auth proxy cannot find credentials in any of the places covered earlier, it follows the logic documented in Setting Up Authentication for Server to Server Production Applications. Some environment (such as Compute Engine, App Engine, and others) provide a default service account that your application can use to authenticate by default. If you use a default service account, it must have the permissions outlined in roles and permissions For more information about Google Cloud's approach to authentication, see Authentication overview.

Create a Service Account

If you are connecting from Compute Engine, make sure your VM has the proper scope to connect using the Cloud SQL Admin API.

Configure the service account to have either of the following access scopes:

https://www.googleapis.com/auth/sqlservice.admin
https://www.googleapis.com/auth/cloud-platform

Go to the Service accounts page of the Google Cloud Console.
Go to the Service accounts page
Select the project that contains your Cloud SQL instance.
Click Create service account.
In the Create service account dialog, enter a descriptive name for the service account.
Change the Service account ID to a unique, recognizable value and then click Create.
For Role, select one of the following roles, click Continue, and then click Done:
- Cloud SQL > Cloud SQL Client
- Cloud SQL > Cloud SQL Editor
- Cloud SQL > Cloud SQL Admin
Click the action menu for your new service account and then select Manage keys.
Click the Add key drop-down menu and then click Create new key.
Confirm that the key type is JSON and then click Create.
The private key file is downloaded to your machine. You can move it to another location. Keep the key file secure.

Download and install the Cloud SQL Auth proxy

Linux 64-bit

Download the Cloud SQL Auth proxy:

wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy

Make the Cloud SQL Auth proxy executable:
```
chmod +x cloud_sql_proxy
```

Linux 32-bit

Download the Cloud SQL Auth proxy:

wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy

Make the Cloud SQL Auth proxy executable:
```
chmod +x cloud_sql_proxy
```

macOS 64-bit

Download the Cloud SQL Auth proxy:

curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64

Make the Cloud SQL Auth proxy executable:
```
chmod +x cloud_sql_proxy
```

macOS 32-bit

Download the Cloud SQL Auth proxy:

curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386

Make the Cloud SQL Auth proxy executable:
```
chmod +x cloud_sql_proxy
```

Windows 64-bit

Right-click https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe and select Save Link As to download the Cloud SQL Auth proxy. Rename the file to cloud_sql_proxy.exe.

Windows 32-bit

Right-click https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe and select Save Link As to download the Cloud SQL Auth proxy. Rename the file to cloud_sql_proxy.exe.

Cloud SQL Auth proxy Docker image

For convenience, the Cloud SQL team maintains several container images that contain the Cloud SQL Auth proxy for use by our customers. For more information about these images, see the Cloud SQL Auth proxy repo on GitHub. You can pull the latest image to your local machine using Docker with the following command:

docker pull gcr.io/cloudsql-docker/gce-proxy:1.21.0

Other OS

For other operating systems not included here, you can compile the Cloud SQL Auth proxy from source.

Start the Cloud SQL Auth proxy

Depending on your language and environment, you can start the Cloud SQL Auth proxy using TCP sockets, Unix sockets, or the Cloud SQL Auth proxy Docker image. The Cloud SQL Auth proxy binary connects to one or more Cloud SQL instances specified on the command line, and opens a local connection as either TCP or a Unix socket. Other applications and services, such as your application code or database management client tools, can connect to Cloud SQL instances through those TCP or Unix socket connections.

TCP sockets

For TCP connections, the Cloud SQL Auth proxy listens on localhost(127.0.0.1) by default. So when you specify tcp:PORT_NUMBER for an instance, the local connection is at 127.0.0.1:PORT_NUMBER.

Alternatively, you can specify a different address for the local connection. For example, here's how to make the Cloud SQL Auth proxy listen at 0.0.0.0:1234 for the local connection:

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234

Copy your INSTANCE_CONNECTION_NAME. This can be found on the Overview page for your instance in the Google Cloud Console. or by running the following command:
```
gcloud sql instances describe INSTANCE_NAME
```
.
For example: myproject:myregion:myinstance.
If the instance has both public and private IP configured, and you want the Cloud SQL Auth proxy to use the private IP address, you must provide the following option when you start the Cloud SQL Auth proxy:
```
-ip_address_types=PRIVATE
```
If you are using a service account to authenticate the Cloud SQL Auth proxy, note the location on your client machine of the private key file that was created when you created the service account.
Start the Cloud SQL Auth proxy.
Some possible Cloud SQL Auth proxy invocation strings:
- Using Cloud SDK authentication:
```
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:5432
```
  The specified port must not already be in use, for example, by a local database server.
- Using a service account and explicitly including the name of the instance connection (recommended for production environments):
```
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAM=tcp:5432 \
                  -credential_file=PATH_TO_KEY_FILE &
```
For more information about Cloud SQL Auth proxy options, see Options for authenticating the Cloud SQL Auth proxy and Options for specifying instances.

Unix sockets

The Cloud SQL Auth proxy can listen on a Unix socket, which is a Posix standard mechanism for using a folder to manage communication between two processes running on the same host. Advantages to using Unix sockets are improved security and lower latency, however, you cannot access a Unix socket from an external machine.

The PostgreSQL standard requires a `.s.PGSQL.5432` suffix in the socket path. Some libraries apply this suffix automatically, but others require you to specify the socket path as follows:

/cloudsql/INSTANCE_CONNECTION_NAME/.s.PGSQL.5432

To create and use a Unix socket, the target directory must exist and both the Cloud SQL Auth proxy and application must have read and write access to it.

If you are using explicit instance specification, copy your INSTANCE_CONNECTION_NAME. This can be found on the Overview page for your instance in the Google Cloud Console. or by running the following command:
```
gcloud sql instances describe INSTANCE_NAME
```
.
For example: myproject:myregion:myinstance.
Create the directory where the Cloud SQL Auth proxy sockets will live:
```
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
```
If you are using a service account to authenticate the Cloud SQL Auth proxy, note the location on your client machine of the private key file that was created when you created the service account.
Open a new terminal window and start the Cloud SQL Auth proxy.
Some possible Cloud SQL Auth proxy invocation strings:
- Using a service account and explicitly including the name of the instance connection (recommended for production environments):
```
./cloud_sql_proxy -dir=/cloudsql -instances=INSTANCE_CONNECTION_NAME
-credential_file=PATH_TO_KEY_FILE &
```
- Using Cloud SDK authentication and automatic instance discovery:
```
./cloud_sql_proxy -dir=/cloudsql &
```
It is best to start the Cloud SQL Auth proxy in its own terminal so you can monitor its output without it mixing with the output from other programs.

For more information about Cloud SQL Auth proxy options, see Options for authenticating the Cloud SQL Auth proxy and Options for specifying instances.

NOTE: When using a unix socket to connect to Cloud SQL using the Cloud SQL Auth proxy, make sure the socket filename's length does not surpass the system's limit. It depends on the system, but it's usually between 91-108 characters. On Linux, the length is usually defined as 108, and you can use the following command to check:

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

Cloud SQL Auth proxy Docker image

To run the Cloud SQL Auth proxy in a Docker container, use the Cloud SQL Auth proxy Docker image available from the Google Container Registry.

You can start the Cloud SQL Auth proxy using either TCP sockets or Unix sockets, with the commands shown below. The options use an INSTANCE_CONNECTION_NAME as the connection string to identify a Cloud SQL instance. You can find the INSTANCE_CONNECTION_NAME on the Overview page for your instance in the Google Cloud Console. or by running the following command:

gcloud sql instances describe INSTANCE_NAME

For example: myproject:myregion:myinstance.

Depending on your language and environment, you can start the Cloud SQL Auth proxy using either TCP sockets or Unix sockets. Unix sockets are not supported for applications written in the Java programming language or for the Windows environment.

Using TCP sockets

docker run -d \\
  -v PATH_TO_KEY_FILE:/config \\
  -p 127.0.0.1:5432:5432 \\
  gcr.io/cloudsql-docker/gce-proxy:1.21.0 /cloud_sql_proxy \\
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:5432 -credential_file=/config

If you are using the credentials provided by your Compute Engine instance, do not include the credential_file parameter and the -v PATH_TO_KEY_FILE:/config line.

Always specify 127.0.0.1 prefix in -p so that the Cloud SQL Auth proxy is not exposed outside the local host. The "0.0.0.0" in the instances parameter is required to make the port accessible from outside of the Docker container.

Using Unix sockets

docker run -d -v /cloudsql:/cloudsql \\
  -v PATH_TO_KEY_FILE:/config \\
  gcr.io/cloudsql-docker/gce-proxy:1.21.0 /cloud_sql_proxy -dir=/cloudsql \\
  -instances=INSTANCE_CONNECTION_NAME -credential_file=/config

If you are using the credentials provided by your Compute Engine instance, do not include the credential_file parameter and the -v PATH_TO_KEY_FILE:/config line.

If you are using a container optimized image, use a writeable directory in place of /cloudsql, for example:

-v /mnt/stateful_partition/cloudsql:/cloudsql

You can specify more than one instance, separated by commas. You can also use Compute Engine metadata to dynamically determine the instances to connect to. Learn more about the Cloud SQL Auth proxy parameters.

Other command-line arguments

The examples above cover the most common use cases, but the Cloud SQL Auth proxy also has other configuration options that can be set with command-line arguments. For help on command-line arguments, use the -help flag to view the latest documentation:

./cloud_sql_proxy -help

See the README on the Cloud SQL Auth proxy GitHub repository for additional examples of how to use Cloud SQL Auth proxy command-line options.

Connect to the Cloud SQL Auth proxy

The connection string you use depends on whether you started the Cloud SQL Auth proxy using a TCP socket or a UNIX socket or Docker.

TCP sockets

Start the psql client:
```
psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
```
Even though the sslmode parameter is set to disable, the Cloud SQL Auth proxy does provide an encrypted connection.

When you connect using TCP sockets, the Cloud SQL Auth proxy is accessed through 127.0.0.1.
If prompted, enter the password.
The psql prompt appears.

Using Unix sockets

Start the psql client:
```
psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME user=USERNAME"
```
Even though the sslmode parameter is set to disable, the Cloud SQL Auth proxy does provide an encrypted connection.
Enter the password.
The psql prompt appears.

Need help? For help troubleshooting the proxy, see Troubleshooting Cloud SQL Auth proxy connections. Or, see our Cloud SQL Support page.

Language-specific 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:5432 &

Python

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

cloud-sql/postgres/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:
    # postgresql+pg8000://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
    sqlalchemy.engine.url.URL.create(
        drivername="postgresql+pg8000",
        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. 5432
        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/postgres/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:postgresql:///<DB_NAME>?cloudSqlInstance=<CLOUD_SQL_CONNECTION_NAME>&
// socketFactory=com.google.cloud.sql.postgres.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:postgresql:///%s", DB_NAME));
config.setUsername(DB_USER); // e.g. "root", "postgres"
config.setPassword(DB_PASS); // e.g. "my-password"

config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.postgres.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/postgres/knex/server.js

View on GitHub

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

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

Go

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

cloudsql/postgres/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. '5432'
	dbName    = mustGetenv("DB_NAME") // e.g. 'my-database'
)

var dbURI string
dbURI = fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s", dbTCPHost, dbUser, dbPwd, dbPort, dbName)

// dbPool is the pool of database connections.
dbPool, err := sql.Open("pgx", 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/postgres/Startup.cs

View on GitHub

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

                // 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.
                Host = Environment.GetEnvironmentVariable("DB_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = 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/postgres/activerecord/config/database.yml

View on GitHub

development:
  adapter: postgresql
  # 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")  { 5432 }%>

PHP

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

cloud_sql/postgres/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('pgsql: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/postgres/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:
    # postgresql+pg8000://<db_user>:<db_pass>@/<db_name>
    #                         ?unix_sock=<socket_path>/<cloud_sql_instance_name>/.s.PGSQL.5432
    sqlalchemy.engine.url.URL.create(
        drivername="postgresql+pg8000",
        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_sock": "{}/{}/.s.PGSQL.5432".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/postgres/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:postgresql:///<DB_NAME>?cloudSqlInstance=<CLOUD_SQL_CONNECTION_NAME>&
// socketFactory=com.google.cloud.sql.postgres.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:postgresql:///%s", DB_NAME));
config.setUsername(DB_USER); // e.g. "root", "postgres"
config.setPassword(DB_PASS); // e.g. "my-password"

config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.postgres.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/postgres/knex/server.js

View on GitHub

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

  // Establish a connection to the database
  return Knex({
    client: 'pg',
    connection: {
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
      host: `${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/postgres/Startup.cs

View on GitHub

// Equivalent connection string:
// "Server=<dbSocketDir>/<INSTANCE_CONNECTION_NAME>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>"
String dbSocketDir = Environment.GetEnvironmentVariable("DB_SOCKET_PATH") ?? "/cloudsql";
String instanceConnectionName = Environment.GetEnvironmentVariable("INSTANCE_CONNECTION_NAME");
var connectionString = new NpgsqlConnectionStringBuilder()
{
    // The Cloud SQL proxy provides encryption between the proxy and instance.
    SslMode = SslMode.Disable,
    // 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.
    Host = String.Format("{0}/{1}", dbSocketDir, instanceConnectionName),
    Username = 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;

Go

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

cloudsql/postgres/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("user=%s password=%s database=%s host=%s/%s", dbUser, dbPwd, dbName, socketDir, instanceConnectionName)

// dbPool is the pool of database connections.
dbPool, err := sql.Open("pgx", 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/postgres/activerecord/config/database.yml

View on GitHub

production:
  adapter: postgresql
  # 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" } %>
  # If connecting via unix domain socket, specify the socket path as host
  host:  "<%= 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/postgres/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(
    'pgsql:dbname=%s;host=%s/%s',
    $dbName,
    $socketDir,
    $connectionName
);

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

Additional topics

Using the Cloud SQL Auth proxy with private IP

To connect to a Cloud SQL instance using private IP, the Cloud SQL Auth proxy must be on a resource with access to the same VPC network as the instance.

The Cloud SQL Auth proxy uses IP to establish a connection with your Cloud SQL instance. By default, the Cloud SQL Auth proxy attempts to connect using a public IPv4 address. If your Cloud SQL instance has only private IP, the Cloud SQL Auth proxy uses the private IP address to connect.

If the instance has both public and private IP configured, and you want the Cloud SQL Auth proxy to use the private IP address, you must provide the following option when you start the Cloud SQL Auth proxy:

-ip_address_types=PRIVATE

Running the Cloud SQL Auth proxy in a separate process

Running the Cloud SQL Auth proxy in a separate terminal process can be useful, to avoid mixing its console output with output from other programs. Use the syntax shown below to invoke the Cloud SQL Auth proxy in a separate process.

Linux

On Linux or macOS, use a trailing & on the command line to launch the Cloud SQL Auth proxy in a separate process:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE &

Windows

In Windows PowerShell, use the Start-Process command to launch the Cloud SQL Auth proxy in a separate process:

Start-Process -filepath "cloud_sql_proxy.exe"
  -ArgumentList "-instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE"

Running the Cloud SQL Auth proxy in a Docker container

To run the Cloud SQL Auth proxy in a Docker container, use the Cloud SQL Auth proxy Docker image available from the Google Container Registry. You can install the Cloud SQL Auth proxy Docker image with this gcloud command:

docker pull gcr.io/cloudsql-docker/gce-proxy:1.21.0

You can start the Cloud SQL Auth proxy using either TCP sockets or Unix sockets, with the commands shown below.

TCP sockets

    docker run -d \
      -v PATH_TO_KEY_FILE:/config \
      -p 127.0.0.1:5432:5432 \
      gcr.io/cloudsql-docker/gce-proxy:1.21.0 /cloud_sql_proxy \
      -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:5432 \
      -credential_file=/config

Unix sockets

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/config \
      gcr.io/cloudsql-docker/gce-proxy:1.21.0 /cloud_sql_proxy -dir=/cloudsql \
      -instances=INSTANCE_CONNECTION_NAME
      -credential_file=/config/PATH_TO_KEY_FILE

If you are using a container optimized image, use a writeable directory in place of /cloudsql, for example:

-v /mnt/stateful_partition/cloudsql:/cloudsql

If you are using the credentials provided by your Compute Engine instance, do not include the credential_file parameter and the -v PATH_TO_KEY_FILE:/config line.

Running the Cloud SQL Auth proxy as a service

Running the Cloud SQL Auth proxy as a background service can be convenient for local development and testing. When you need to access your Cloud SQL instance, you can start the service in the background and stop it when you are finished.

The Cloud SQL Auth proxy doesn't currently provide built-in support for running as a Windows service, but third-party service managers can be used to run it as a service. For example, you can use NSSM to configure the Cloud SQL Auth proxy as a Windows service, and NSSM monitors the Cloud SQL Auth proxy and restarts it automatically if it stops responding. See the NSSM documentation for more information.

Tips for working with Cloud SQL Auth proxy

Invoking the Cloud SQL Auth proxy

All of the example proxy invocations start the Cloud SQL Auth proxy in the background, so a prompt is returned. It is preferable to reserve that terminal for the Cloud SQL Auth proxy, to avoid having its output mixed with the output from other programs. Also, the output from the Cloud SQL Auth proxy can help you diagnose connection problems, so it can be helpful to capture in a log file. If you do not start the Cloud SQL Auth proxy in the background, the output goes to stdout unless redirected.

You do not have to use /cloudsql as the directory for the Cloud SQL Auth proxy sockets. (That directory name was chosen to minimize differences with App Engine connection strings.) If you change the directory name, however, keep the overall length to a minimum; it is incorporated in a longer string that has a length limit imposed by the operating system. It depends on the system, but it's usually between 91-108 characters. On Linux, the length is usually defined as 108, and you can use the following command to check:

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

Using the Cloud SQL Auth proxy to connect to multiple instances

You can use one local Cloud SQL Auth proxy client to connect to multiple Cloud SQL instances. The way you do this depends on whether you are using Unix sockets or TCP.

Unix sockets

To connect the Cloud SQL Auth proxy to multiple instances, you provide the instance connection names with the `-instances` parameter, in a comma-separated list (no spaces). The Cloud SQL Auth proxy connects to each instance when it starts.

You connect to each instance using its socket, in the specified directory.

For example:

      ./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance,myProject:us-central1:myInstance2 &
      psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2

TCP sockets

When you connect using TCP, you specify a port on your machine for the Cloud SQL Auth proxy to listen on for each Cloud SQL instance. When connecting to multiple Cloud SQL instances, each port specified must be unique and available for use on your machine.

For example:

    # Start the Cloud SQL Auth proxy to connect to two different Cloud SQL instances
    # Give the Cloud SQL Auth proxy a unique port on your machine to use for each Cloud SQL instance.

    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:5432,myProject:us-central1:myInstance2=tcp:1234

    # Connect to "myInstance" using port 5432 on your machine:
    psql -U myUser -h 127.0.0.1  --port 5432

    # Connect to "myInstance2" using port 1234 on your machine:
    psql -U myUser -h 127.0.0.1  --port 1234

Cloud SQL Auth proxy invocations and psql client connection strings

You can use Cloud SQL Auth proxy invocations and connection strings, for example, in commands for a PostgreSQL user myUser, for the myInstance instance, located in us-central1, in the myProject project.

Using automatic instance discovery with gcloud credentials:

    ./cloud_sql_proxy -dir=/cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance

Using project discovery with gcloud credentials:

    ./cloud_sql_proxy -dir=/cloudsql -projects=myProject &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance

For a Compute Engine instance, with explicit instance specification:

    ./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance

For Unix, using TCP:

    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:5432 &
    psql -U myUser -h 127.0.0.1

For Windows (at the command line prompt):

    cloud_sql_proxy.exe -instances=myProject:us-central1:myInstance=tcp:5432
    psql -U myUser -h 127.0.0.1

For more information about Cloud SQL Auth proxy options and connection strings, see the Cloud SQL Auth proxy GitHub page.

Troubleshooting Cloud SQL Auth proxy connections

The Cloud SQL Auth proxy Docker image is based on a specific version of the Cloud SQL Auth proxy. When a new version of the Cloud SQL Auth proxy becomes available, pull the new version of the Cloud SQL Auth proxy Docker image to keep your environment up to date. You can see the current version of the Cloud SQL Auth proxy by checking the Cloud SQL Auth proxy GitHub releases page.

If you are having trouble connecting to your Cloud SQL instance using the Cloud SQL Auth proxy, here are a few things to try to find what's causing the problem.

Check the Cloud SQL Auth proxy output.

Often, the Cloud SQL Auth proxy output can help you determine the source of the problem and how to solve it. Pipe the output to a file, or watch the terminal where you started the Cloud SQL Auth proxy.
If you are getting a 403 notAuthorized error, and you are using a service account to authenticate the Cloud SQL Auth proxy, make sure the service account has the correct permissions.

You can check the service account by searching for its ID on the IAM page. It must have the cloudsql.instances.connect permission. The Cloud SQL Admin, Client and Editor predefined roles have this permission.
Make sure to enable the Cloud SQL Admin API.

If it is not, you see output like Error 403: Access Not Configured in your Cloud SQL Auth proxy logs.
If you are including multiple instances in your instances list, make sure you are using a comma as a delimiter, with no spaces. If you are using TCP, make sure you are specifying different ports for each instance.
If you are connecting using UNIX sockets, confirm that the sockets were created by listing the directory you provided when you started the Cloud SQL Auth proxy.
If you have an outbound firewall policy, make sure it allows connections to port 3307 on the target Cloud SQL instance.

Note: Port 3307 is used by the Cloud SQL Auth proxy to connect to the Cloud SQL Auth proxy server. Port 5432 is the default port for the PostgreSQL protocol over a direct TCP connection (not using the Cloud SQL Auth proxy).

What's next

Learn more about the Cloud SQL Auth proxy.
Learn more about Identity and Access Management (IAM).
Learn more about Service Accounts.
Learn about the two levels of access control for Cloud SQL instances.
Create users and databases.
Learn about connecting to your instance from your application.
Learn about the psql Client.
Learn about options for support.

Connecting using the Cloud SQL Auth proxy

Before you begin

Options for authenticating the Cloud SQL Auth proxy

Credentials supplied by the credential_file flag.

Credentials supplied by an access token.

Credentials supplied by an environment variable.

Credentials from an authenticated Cloud SDK client.

Credentials associated with the Compute Engine instance.

Environment's default service account

Create a Service Account

Download and install the Cloud SQL Auth proxy

Linux 64-bit

Linux 32-bit

macOS 64-bit

macOS 32-bit

Windows 64-bit

Windows 32-bit

Cloud SQL Auth proxy Docker image

Other OS

Start the Cloud SQL Auth proxy

TCP sockets

Unix sockets

Cloud SQL Auth proxy Docker image

Using TCP sockets

Using Unix sockets

Other command-line arguments

Connect to the Cloud SQL Auth proxy

TCP sockets

Using Unix sockets

Language-specific code samples

Connecting with TCP

Python

Java

Node.js

Go

C#

Ruby

PHP

Connecting with Unix sockets

Python

Java

Node.js

C#

Go

Ruby

PHP

Additional topics

Using the Cloud SQL Auth proxy with private IP

Running the Cloud SQL Auth proxy in a separate process

Linux

Windows

Running the Cloud SQL Auth proxy in a Docker container

TCP sockets

Unix sockets

Running the Cloud SQL Auth proxy as a service

Tips for working with Cloud SQL Auth proxy

Invoking the Cloud SQL Auth proxy

Using the Cloud SQL Auth proxy to connect to multiple instances

Unix sockets

TCP sockets

Cloud SQL Auth proxy invocations and psql client connection strings

Troubleshooting Cloud SQL Auth proxy connections

What's next