Cloud SQL Auth Proxy

[![CI][ci-badge]][ci-build]

[!WARNING] Go versions 1.25.2 and 1.24.8 are NOT compatible with Cloud Auth Proxy.

An update to the Go version 1.25.2 and Go 1.24.8 breaks SAN verificaton. This is because Cloud SQL includes a trailing dot in the DNS name within the certificate's Subject Alternative Name (SAN), which the above Go versions reject as a malformed DNS name.

For more details, please see the related Go issue: crypto/x509: quadratic complexity when checking name constraints .

[!IMPORTANT]

The Cloud SQL Auth Proxy does not currently support Unix domain socket connections to MySQL 8.4 instances. This is due to a known issue involving the new default caching_sha2_password authentication plugin.

The Cloud SQL Auth Proxy is a utility for ensuring secure connections to your Cloud SQL instances. It provides IAM authorization, allowing you to control who can connect to your instance through IAM permissions, and TLS 1.3 encryption, without having to manage certificates.

See the [Connecting Overview][connection-overview] page for more information on connecting to a Cloud SQL instance, or the [About the Proxy][about-proxy] page for details on how the Cloud SQL Proxy works.

The Cloud SQL Auth Proxy has support for:

• [Automatic IAM Authentication][iam-auth] (Postgres and MySQL only)
• Metrics (Cloud Monitoring, Cloud Trace, and Prometheus)
• [HTTP Healthchecks][health-check-example]
• Service account impersonation
• Separate Dialer functionality released as the Cloud SQL Go Connector
• Configuration with environment variables
• Fully POSIX-compliant flags

If you're using Go, Java, Python, or Node.js, consider using the corresponding Cloud SQL connector which does everything the Proxy does, but in process:

• Cloud SQL Go connector
• Cloud SQL Java connector
• Cloud SQL Python connector
• Cloud SQL Node.js connector

For users migrating from v1, see the Migration Guide. The v1 README is still available.

[!IMPORTANT]

The Proxy does not configure the network between the VM it's running on and the Cloud SQL instance. You MUST ensure the Proxy can reach your Cloud SQL instance, either by deploying it in a VPC that has access to your Private IP instance, or by configuring Public IP.

Installation

Check for the latest version on the [releases page][releases] and use the following instructions for your OS and CPU architecture.

[!NOTE]

Starting with version v2.17.1, Windows binaries provided on the [releases page][releases] are signed with Google LLC certificates.

Linux amd64

# see Releases for other versions
URL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.23.0"

curl "$URL/cloud-sql-proxy.linux.amd64" -o cloud-sql-proxy

chmod +x cloud-sql-proxy

Linux 386

# see Releases for other versions
URL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.23.0"

curl "$URL/cloud-sql-proxy.linux.386" -o cloud-sql-proxy

chmod +x cloud-sql-proxy

Linux arm64

# see Releases for other versions
URL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.23.0"

curl "$URL/cloud-sql-proxy.linux.arm64" -o cloud-sql-proxy

chmod +x cloud-sql-proxy

Linux arm

# see Releases for other versions
URL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.23.0"

curl "$URL/cloud-sql-proxy.linux.arm" -o cloud-sql-proxy

chmod +x cloud-sql-proxy

Mac (Intel)

# see Releases for other versions
URL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.23.0"

curl "$URL/cloud-sql-proxy.darwin.amd64" -o cloud-sql-proxy

chmod +x cloud-sql-proxy

Mac (Apple Silicon)

# see Releases for other versions
URL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.23.0"

curl "$URL/cloud-sql-proxy.darwin.arm64" -o cloud-sql-proxy

chmod +x cloud-sql-proxy

Windows x64

# see Releases for other versions
curl https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.23.0/cloud-sql-proxy.x64.exe -o cloud-sql-proxy.exe

Windows x86

# see Releases for other versions
curl https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.23.0/cloud-sql-proxy.x86.exe -o cloud-sql-proxy.exe

Install from Source

To install from source, ensure you have the latest version of Go installed.

Then, simply run:

go install github.com/GoogleCloudPlatform/cloud-sql-proxy/v2@latest

The cloud-sql-proxy will be placed in $GOPATH/bin or $HOME/go/bin.

Usage

The following examples all reference an INSTANCE_CONNECTION_NAME, which takes the form: myproject:myregion:myinstance.

To find your Cloud SQL instance's INSTANCE_CONNECTION_NAME, visit the detail page of your Cloud SQL instance in the console, or use gcloud with:

gcloud sql instances describe <INSTANCE_NAME> --format='value(connectionName)'

Credentials

The Cloud SQL Proxy uses a Cloud IAM principal to authorize connections against a Cloud SQL instance. The Proxy sources the credentials using Application Default Credentials.

[!NOTE]

Any IAM principal connecting to a Cloud SQL database will need one of the following IAM roles:

• Cloud SQL Client (preferred)
• Cloud SQL Editor
• Cloud SQL Admin

Or one may manually assign the following IAM permissions:

• cloudsql.instances.connect
• cloudsql.instances.get

See [Roles and Permissions in Cloud SQL][roles-and-permissions] for details.

When the Proxy authenticates under the Compute Engine VM's default service account, the VM must have at least the sqlservice.admin API scope (i.e., "https://www.googleapis.com/auth/sqlservice.admin") and the associated project must have the SQL Admin API enabled. The default service account must also have at least writer or editor privileges to any projects of target SQL instances.

The Proxy also supports two flags related to credentials:

• --token to use an OAuth2 token
• --credentials-file to use a service account key file

Basic Usage

To start the Proxy, use:

# starts the Proxy listening on localhost with the default database engine port
# For example:
#   MySQL      localhost:3306
#   Postgres   localhost:5432
#   SQL Server localhost:1433
./cloud-sql-proxy <INSTANCE_CONNECTION_NAME>

The Proxy will automatically detect the default database engine's port and start a corresponding listener. Production deployments should use the --port flag to reduce startup time.

The Proxy supports multiple instances:

./cloud-sql-proxy <INSTANCE_CONNECTION_NAME_1> <INSTANCE_CONNECTION_NAME_2>

Configuring Port

To override the port, use the --port flag:

# Starts a listener on localhost:6000
./cloud-sql-proxy --port 6000 <INSTANCE_CONNECTION_NAME>

When specifying multiple instances, the port will increment from the flag value:

# Starts a listener on localhost:6000 for INSTANCE_CONNECTION_1
# and localhost:6001 for INSTANCE_CONNECTION_NAME_2.
./cloud-sql-proxy --port 6000 <INSTANCE_CONNECTION_NAME_1> <INSTANCE_CONNECTION_NAME_2>

To configure ports on a per instance basis, use the port query param:

# Starts a listener on localhost:5000 for the instance called "postgres"
# and starts a listener on localhost:6000 for the instance called "mysql"
./cloud-sql-proxy \
    'myproject:my-region:postgres?port=5000' \
    'myproject:my-region:mysql?port=6000'

Configuring Listening Address

To override the choice of localhost, use the --address flag:

# Starts a listener on all interfaces at port 5432
./cloud-sql-proxy --address 0.0.0.0 <INSTANCE_CONNECTION_NAME>

To override address on a per-instance basis, use the address query param:

# Starts a listener on 0.0.0.0 for "postgres" at port 5432
# and a listener on 10.0.0.1:3306 for "mysql"
./cloud-sql-proxy \
    'myproject:my-region:postgres?address=0.0.0.0' \
    'myproject:my-region:mysql?address=10.0.0.1"

Configuring Private IP

By default, the Proxy attempts to connect to an instance's public IP. To enable private IP, use:

# Starts a listener connected to the private IP of the Cloud SQL instance.
# Note: there must be a network path present for this to work.
./cloud-sql-proxy --private-ip <INSTANCE_CONNECTION_NAME>

[!IMPORTANT]

The Proxy does not configure the network. You MUST ensure the Proxy can reach your Cloud SQL instance, either by deploying it in a VPC that has access to your Private IP instance, or by configuring Public IP.

Configuring Unix domain sockets

The Proxy also supports Unix domain sockets. To start the Proxy with Unix sockets, run:

# Uses the directory "/mycooldir" to create a Unix socket
# For example, the following directory would be created:
#   /mycooldir/myproject:myregion:myinstance
./cloud-sql-proxy --unix-socket /mycooldir <INSTANCE_CONNECTION_NAME>

To configure a Unix domain socket on a per-instance basis, use the unix-socket query param:

# Starts a TCP listener on localhost:5432 for "postgres"
# and creates a Unix domain socket for "mysql":
#     /cloudsql/myproject:my-region:mysql
./cloud-sql-proxy \
    myproject:my-region:postgres \
    'myproject:my-region:mysql?unix-socket=/cloudsql'

[!NOTE]

The Proxy supports Unix domain sockets on recent versions of Windows, but replaces colons with periods:

```shell

Starts a Unix domain socket at the path:

C:\cloudsql\myproject.my-region.mysql

./cloud-sql-proxy --unix-socket C:\cloudsql myproject:my-region:mysql ```

Configuring IAM Database Authentication

The Proxy supports [Automatic IAM Database Authentication][iam-auth] for MySQL and Postgres instances, allowing IAM principal's to authenticate and connect as database users.

Make sure to configure your [Cloud SQL instance to allow IAM authentication][iam-auth-config] and to [add your IAM principal as a database user][iam-auth-user].

./cloud-sql-proxy --auto-iam-authn <INSTANCE_CONNECTION_NAME>

[!IMPORTANT]

Make sure to run the Proxy as the same IAM principal as the database user you want to log in as. Only the IAM principal that is attached to the sourced credentials will be able to successfully log in via automatic IAM database authentication.

When logging in using an IAM database user, Cloud SQL truncates usernames based on the engine type in order to not exceed character limits. PostgreSQL's username character limit is 63, while MySQL's is 32.

Cloud SQL IAM database usernames are formatted in the following way:

Postgres: * For an IAM user account, this is the user's email address. * For a service account, it is the service account's email without the .gserviceaccount.com domain suffix.

MySQL: * For an IAM user account, this is the user's email address, without the @ or domain name. For example, for test-user@gmail.com, the database user would be test-user. * For a service account, this is the service account's email address without the @project-id.iam.gserviceaccount.com suffix.

Configuring Service Account Impersonation

The Proxy supports service account impersonation. This allows the Proxy to act as a different service account, which can be useful for granting access to resources that are not accessible to the default IAM principal.

To use service account impersonation, you must have the iam.serviceAccounts.getAccessToken permission on the IAM principal impersonating another service account. You can grant this permission by assigning the roles/iam.serviceAccountTokenCreator role to the IAM principal.

To impersonate a service account, use the --impersonate-service-account flag:

[!NOTE]

The impersonated service account must have the Service Usage Consumer and Cloud SQL Client permissions. Additionally, to use IAM Authenticated users, add the Cloud SQL Instance User permission.

```shell

Starts a listener on localhost:5432 and impersonates the service account

"my-other-sa@my-project.iam.gserviceaccount.com".

The Proxy will use the credentials of the principal running the Proxy to

generate a short-lived access token for the impersonated service account.

./cloud-sql-proxy --impersonate-service-account \ my-other-sa@my-project.iam.gserviceaccount.com