Repository files navigation

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

See theConnecting Overview page for more information onconnecting to a Cloud SQL instance, or theAbout the Proxy pagefor details on how the Cloud SQL Proxy works.

The Cloud SQL Auth Proxy has support for:

• Automatic IAM Authentication (Postgres and MySQL only)
• Metrics (Cloud Monitoring,Cloud Trace, andPrometheus)
• HTTP Healthchecks
• Service account impersonation
• Separate Dialer functionality released as theCloud SQL Go Connector
• Configuration withenvironment variables
• Fully POSIX-compliant flags

If you're using Go, Java, Python, or Node.js, consider using the corresponding Cloud SQLconnector 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 theMigration Guide.Thev1 README is still available.

Check for the latest version on thereleases page and use thefollowing instructions for your OS and CPU architecture.

# see Releases for other versionsURL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.18.0"curl"$URL/cloud-sql-proxy.linux.amd64" -o cloud-sql-proxychmod +x cloud-sql-proxy

# see Releases for other versionsURL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.18.0"curl"$URL/cloud-sql-proxy.linux.386" -o cloud-sql-proxychmod +x cloud-sql-proxy

# see Releases for other versionsURL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.18.0"curl"$URL/cloud-sql-proxy.linux.arm64" -o cloud-sql-proxychmod +x cloud-sql-proxy

# see Releases for other versionsURL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.18.0"curl"$URL/cloud-sql-proxy.linux.arm" -o cloud-sql-proxychmod +x cloud-sql-proxy

# see Releases for other versionsURL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.18.0"curl"$URL/cloud-sql-proxy.darwin.amd64" -o cloud-sql-proxychmod +x cloud-sql-proxy

# see Releases for other versionsURL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.18.0"curl"$URL/cloud-sql-proxy.darwin.arm64" -o cloud-sql-proxychmod +x cloud-sql-proxy

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

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

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

Then, simply run:

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

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

The following examples all reference anINSTANCE_CONNECTION_NAME, which takesthe form:myproject:myregion:myinstance.

To find your Cloud SQL instance'sINSTANCE_CONNECTION_NAME, visit the detailpage of your Cloud SQL instance in the console, or usegcloud with:

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

The Cloud SQL Proxy uses a Cloud IAM principal to authorize connections againsta Cloud SQL instance. The Proxy sources the credentials usingApplication Default Credentials.

When the Proxy authenticates under the Compute Engine VM's default serviceaccount, the VM must have at least thesqlservice.admin API scope (i.e.,"https://www.googleapis.com/auth/sqlservice.admin") and the associated projectmust have the SQL Admin API enabled. The default service account must also haveat 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

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 starta corresponding listener. Production deployments should use the--port flag toreduce startup time.

The Proxy supports multiple instances:

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

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 theport 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'

To override the choice oflocalhost, 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 theaddress 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"

By default, the Proxy attempts to connect to an instance's public IP. To enableprivate 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>

The Proxy also supportsUnix 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 theunix-socketquery 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'

# 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

The Proxy supportsAutomatic IAM Database Authentication for MySQLand Postgres instances, allowing IAM principal's to authenticate and connectas database users.

Make sure to configure yourCloud SQL instance to allow IAM authenticationand toadd your IAM principal as a database user.

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

The Proxy supportsservice account impersonation.This allows the Proxy to act as a different service account, which can be usefulfor granting access to resources that are not accessible to the default IAMprincipal.

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

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

# 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<INSTANCE_CONNECTION_NAME>

The Proxy can be configured to use DNS to look up an instance. This wouldallow you to configure your application to connect to a database instance, andcentrally configure which instance in your DNS zone.

Add a DNS TXT record for the Cloud SQL instance to aprivate DNS serveror a private Google Cloud DNS Zone used by your application.

Note: You are strongly discouraged from adding DNS records for yourCloud SQL instances to a public DNS server. This would allow anyone on theinternet to discover the Cloud SQL instance name.

For example: suppose you wanted to use the domain nameprod-db.mycompany.example.com to connect to your database instancemy-project:region:my-instance. You would create the following DNS record:

• Record type:TXT
• Name:prod-db.mycompany.example.com – This is the domain name used by the application
• Value:my-project:region:my-instance – This is the instance name

Configure the Proxy with your DNS domain name instead of an instance connectionname:

./cloud-sql-proxy prod-db.mycompany.example.com

When the Proxy is configured using a domain name, it willperiodically check if the DNS record for an instance changes. When the Proxydetects that the domain name refers to a different instance, it willclose all open connections to the old instance. Subsequent connection attemptswill be directed to the new instance.

For example: suppose application is configured to connect using thedomain nameprod-db.mycompany.example.com. Initially the corporate DNSzone has a TXT record with the valuemy-project:region:my-instance. Theapplication establishes connections to themy-project:region:my-instanceCloud SQL instance.

Then, to reconfigure the application to use a different databaseinstance, change the value of theprod-db.mycompany.example.com DNS recordfrommy-project:region:my-instance tomy-project:other-region:my-instance-2

The Proxy detects the change to this DNS record.Now, when the application connects to its database using thedomain nameprod-db.mycompany.example.com, it will connect to themy-project:other-region:my-instance-2 Cloud SQL instance.

The Proxy will automatically close all existing connections tomy-project:region:my-instance. This will force the connection pools toestablish new connections. Also, it may cause database queries in progressto fail.

The Proxy will poll for changes to the DNS name every 30 seconds by default.

The Proxy includes support for a connection test on startup. This test helpsensure the Proxy can reach the associated instance and is a quick debuggingtool. The test will attempt to connect to the specified instance(s) and failif the instance is unreachable. If the test fails, the Proxy will exit witha non-zero exit code.

./cloud-sql-proxy --run-connection-test<INSTANCE_CONNECTION_NAME>

The Proxy supports a configuration file. Supported file types are TOML, JSON,and YAML. Load the file with the--config-file flag:

./cloud-sql-proxy --config-file /path/to/config.[toml|json|yaml]

The configuration file format supports all flags. The key names should matchthe flag names. For example:

# use instance-connection-name-0, instance-connection-name-1, etc.# for multiple instancesinstance-connection-name ="proj:region:inst"auto-iam-authn =truedebug =truedebug-logs =true

Run./cloud-sql-proxy --help for more details. See the full documentationindocs/cmd.

The proxy supports configuration through environment variables.Each environment variable uses "CSQL_PROXY" as a prefix and isthe uppercase version of the flag using underscores as word delimiters.

For example, the--auto-iam-authn flag may be set with the environment variableCSQL_PROXY_AUTO_IAM_AUTHN.

An invocation of the Proxy using environment variables would look like the following:

CSQL_PROXY_AUTO_IAM_AUTHN=true\    ./cloud-sql-proxy<INSTANCE_CONNECTION_NAME>

Run./cloud-sql-proxy --help for more details.

The--lazy-refresh flag configures the Proxy to retrieve connection infolazily and as-needed. Otherwise, no background refresh cycle runs. This settingis useful in environments where the CPU may be throttled outside of a requestcontext, e.g., Cloud Run, Cloud Functions, etc.

To see a full list of flags, use:

./cloud-sql-proxy --help

There are containerized versions of the Proxy available from the followingArtifact Registry repositories:

• gcr.io/cloud-sql-connectors/cloud-sql-proxy
• us.gcr.io/cloud-sql-connectors/cloud-sql-proxy
• eu.gcr.io/cloud-sql-connectors/cloud-sql-proxy
• asia.gcr.io/cloud-sql-connectors/cloud-sql-proxy

Each image is tagged with the associated Proxy version. The following tags arecurrently supported:

• $VERSION (default)
• $VERSION-alpine
• $VERSION-bullseye
• $VERSION-bookworm

The$VERSION is the Proxy version without the leading "v" (e.g.,2.18.0).

For example, to pull a particular version, use a command like:

# $VERSION is 2.18.0docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.18.0

We recommend pinning to a specific version tag and using automation with a CI pipelineto update regularly.

The default container image usesdistroless with a non-root user. If youneed a shell or related tools, use the Alpine or Debian-based container images(bullseye or bookworm) listed above.

The containers have the proxy as anENTRYPOINT so, to use the proxy from acontainer, all you need to do is specify options using the command, and exposethe proxy's internal port to the host. For example, you can use:

docker run --publish<host-port>:<proxy-port> \    gcr.io/cloud-sql-connectors/cloud-sql-proxy:latest \    --address"0.0.0.0" --port<proxy-port><instance-connection-name>

You'll need the--address "0.0.0.0" so that the proxy doesn't only listen forconnections originating fromwithin the container.

You will need to authenticate using one of the methods outlined in thecredentials section. If using a credentials file you must mountthe file and ensure that the non-root user that runs the proxy hasread accessto the file. These alternatives might help:

1. Change the group of your local file and add read permissions to the groupwithchgrp 65532 key.json && chmod g+r key.json.
2. If you can't control your file's group, you can directly change the publicpermissions of your file by doingchmod o+r key.json.

For example, a full command using a JSON credentials file might look like

docker run \    --publish<host-port>:<proxy-port> \    --mount type=bind,source="$(pwd)"/sa.json,target=/config/sa.json \    gcr.io/cloud-sql-connectors/cloud-sql-proxy:latest \    --address 0.0.0.0 \    --port<proxy-port> \    --credentials-file /config/sa.json<instance-connection-name>

See theexample here as well asConnecting from GoogleKubernetes Engine.

The Cloud SQL Auth Proxy includes support for sending requests through a SOCKS5proxy. If a SOCKS5 proxy is running onlocalhost:8000, the command to startthe Cloud SQL Auth Proxy would look like:

ALL_PROXY=socks5://localhost:8000 \HTTPS_PROXY=socks5://localhost:8000 \    cloud-sql-proxy <INSTANCE_CONNECTION_NAME>

TheALL_PROXY environment variable specifies the proxy for all TCPtraffic to and from a Cloud SQL instance. TheALL_PROXY environment variablesupportssocks5 andsocks5h protocols. To route DNS lookups through a proxy,use thesocks5h protocol.

TheHTTPS_PROXY (orHTTP_PROXY) specifies the proxy for all HTTP(S) trafficto the SQL Admin API. SpecifyingHTTPS_PROXY orHTTP_PROXY is only necessarywhen you want to proxy this traffic. Otherwise, it is optional. Seehttp.ProxyFromEnvironmentfor possible values.

The Proxy supportsCloud Monitoring,Cloud Trace, andPrometheus.

Supported metrics include:

• cloudsqlconn/dial_latency: The distribution of dialer latencies (ms)
• cloudsqlconn/open_connections: The current number of open Cloud SQLconnections
• cloudsqlconn/dial_failure_count: The number of failed dial attempts
• cloudsqlconn/refresh_success_count: The number of successful certificaterefresh operations
• cloudsqlconn/refresh_failure_count: The number of failed refreshoperations.

Supported traces include:

• cloud.google.com/go/cloudsqlconn.Dial: The dial operation includingrefreshing an ephemeral certificate and connecting the instance
• cloud.google.com/go/cloudsqlconn/internal.InstanceInfo: The call to retrieveinstance metadata (e.g., database engine type, IP address, etc)
• cloud.google.com/go/cloudsqlconn/internal.Connect: The connection attemptusing the ephemeral certificate
• SQL Admin API client operations

To enable Cloud Monitoring and Cloud Trace, use the--telemetry-project flagwith the project where you want to view metrics and traces. To configure themetrics prefix used by Cloud Monitoring, use the--telemetry-prefix flag. Whenenabling telemetry, both Cloud Monitoring and Cloud Trace are enabled. Todisable Cloud Monitoring, use--disable-metrics. To disable Cloud Trace, use--disable-traces.

To enable Prometheus, use the--prometheus flag. This will start an HTTPserver on localhost with a/metrics endpoint. The Prometheus namespace mayoptionally be set with--prometheus-namespace.

To enable debug logging to report on internal certificate refresh operations,use the--debug-logs flag. Typical use of the Proxy should not require debuglogs, but if you are surprised by the Proxy's behavior, debug logging shouldprovide insight into internal operations and can help when reporting issues.

The Proxy includes support for an admin server on localhost. By default, thethe admin server is not enabled. To enable the server, pass the --debug or--quitquitquit flag. This will start the server on localhost at port 9091.To change the port, use the --admin-port flag.

When --debug is set, the admin server enables Go's profiler available at/debug/pprof/.

See thedocumentation on pprof for details on how to use theprofiler.

When --quitquitquit is set, the admin server adds an endpoint at/quitquitquit. The admin server exits gracefully when it receives a GET or POSTrequest at /quitquitquit.

The Proxy is a convenient way to control access to your database using IAMpermissions while ensuring a secure connection to your Cloud SQL instance. Whenusing the Proxy, you do not have to manage database client certificates,configured Authorized Networks, or ensure clients connect securely. The Proxyhandles all of this for you.

The Proxy is a gateway to your Cloud SQL instance. Clients connect to the Proxyover an unencrypted connection and are authorized using the environment's IAMprincipal. The Proxy then encrypts the connection to your Cloud SQL instance.

Because client connections are not encrypted and authorized using theenvironment's IAM principal, we recommend running the Proxy on the same VM orKubernetes pod as your application and using the Proxy's default behavior ofallowing connections from only the local network interface. This is the mostsecure configuration: unencrypted traffic does not leave the VM, and onlyconnections from applications on the VM are allowed.

Here are some common examples of how to run the Proxy in different environments:

• Connect to Cloud SQL for MySQL from your local computer
• Connect to Cloud SQL for MySQL from Google Kubernetes Engine

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

We recommend deploying the Proxy on the host machines that are running theapplication. However, large deployments may exceed the request quota for the SQLAdmin API . If your Proxy reports request quota errors, we recommend deployingthe Proxy with a connection pooler likepgbouncer orProxySQL. Fordetails, seeRunning the Cloud SQL Proxy as a Service.

Instead of using a single Proxy across multiple applications, we recommend usingone Proxy instance for every application process. The Proxy uses the context'sIAM principal and so have a 1-to-1 mapping between application and IAM principalis best. If multiple applications use the same Proxy instance, then it becomesunclear from an IAM perspective which principal is doing what.

After downloading a binary from the releases page, copy the sha256sum valuethat corresponds with the binary you chose.

Then run this command (make sure to add the asterisk before the file name):

echo'<RELEASE_PAGE_SHA_HERE> *<NAME_OF_FILE_HERE>'| shasum -c

For example, after downloading the v2.1.0 release of the Linux AMD64 Proxy, youwould run:

$echo"547b24faf0dfe5e3d16bbc9f751dfa6b34dfd5e83f618f43a2988283de5208f2 *cloud-sql-proxy"| shasum -ccloud-sql-proxy: OK

If you seeOK, the binary is a verified match.

• Cloud SQL
• Cloud SQL Auth Proxy Documentation
• Cloud SQL Auth Proxy Quickstarts
• Cloud SQL Code Samples
• Cloud SQL Auth Proxy Package Documentation

This project usessemantic versioning, and uses thefollowing lifecycle regarding support for a major version:

• Active - Active versions get all new features and security fixes (thatwouldn’t otherwise introduce a breaking change). New major versions areguaranteed to be "active" for a minimum of 1 year.

• Maintenance - Maintenance versions continue to receive security and criticalbug fixes, but do not receive new features.

The Cloud SQL Auth Proxy aims for a minimum monthly release cadence. If no newfeatures or fixes have been added, a new PATCH version with the latestdependencies is released.

We support releases for 1 year from the release date.

Contributions are welcome. Please, see theCONTRIBUTING documentfor details.

Please note that this project is released with a Contributor Code of Conduct.By participating in this project you agree to abide by its terms. SeeContributor Code of Conduct for more information.