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 page for more information on connecting to a Cloud SQL instance, or the About the Proxy page for 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, and Prometheus)
- HTTP Healthchecks
- 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.
Check for the latest version on the releases page and use the following instructions for your OS and CPU architecture.
Linux amd64
# see Releases for other versions
URL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3"
curl "$URL/cloud-sql-proxy.linux.amd64" -o cloud-sql-proxy
chmod +x cloud-sql-proxyLinux 386
# see Releases for other versions
URL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3"
curl "$URL/cloud-sql-proxy.linux.386" -o cloud-sql-proxy
chmod +x cloud-sql-proxyLinux arm64
# see Releases for other versions
URL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3"
curl "$URL/cloud-sql-proxy.linux.arm64" -o cloud-sql-proxy
chmod +x cloud-sql-proxyLinux arm
# see Releases for other versions
URL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3"
curl "$URL/cloud-sql-proxy.linux.arm" -o cloud-sql-proxy
chmod +x cloud-sql-proxyMac (Intel)
# see Releases for other versions
URL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3"
curl "$URL/cloud-sql-proxy.darwin.amd64" -o cloud-sql-proxy
chmod +x cloud-sql-proxyMac (Apple Silicon)
# see Releases for other versions
URL="https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3"
curl "$URL/cloud-sql-proxy.darwin.arm64" -o cloud-sql-proxy
chmod +x cloud-sql-proxyWindows x64
# see Releases for other versions
curl https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3/cloud-sql-proxy.x64.exe -o cloud-sql-proxy.exeWindows x86
# see Releases for other versions
curl https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3/cloud-sql-proxy.x86.exe -o cloud-sql-proxy.exeTo install from source, ensure you have the latest version of Go installed.
Then, simply run:
go install github.com/GoogleCloudPlatform/cloud-sql-proxy/v2@latestThe cloud-sql-proxy will be placed in $GOPATH/bin or $HOME/go/bin.
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)'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.connectcloudsql.instances.get
See Roles and Permissions in Cloud SQL 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 three flags related to credentials:
--tokento use an OAuth2 token--credentials-fileto use a service account key file--gcloud-authto use the Gcloud user's credentials (local development only)
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>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'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"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.
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:
# 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 includes support for a connection test on startup. This test helps ensure the Proxy can reach the associated instance and is a quick debugging tool. The test will attempt to connect to the specified instance(s) and fail if the instance is unreachable. If the test fails, the Proxy will exit with a 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 match the flag names. For example:
# use instance-connection-name-0, instance-connection-name-1, etc.
# for multiple instances
instance-connection-name = "proj:region:inst"
auto-iam-authn = true
debug = true
debug-logs = trueRun ./cloud-sql-proxy --help for more details.
The --lazy-refresh flag configures the Proxy to retrieve connection info
lazily and as-needed. Otherwise, no background refresh cycle runs. This setting
is useful in environments where the CPU may be throttled outside of a request
context, e.g., Cloud Run, Cloud Functions, etc.
To see a full list of flags, use:
./cloud-sql-proxy --helpThere are containerized versions of the Proxy available from the following Google Cloud Container Registry repositories:
gcr.io/cloud-sql-connectors/cloud-sql-proxyus.gcr.io/cloud-sql-connectors/cloud-sql-proxyeu.gcr.io/cloud-sql-connectors/cloud-sql-proxyasia.gcr.io/cloud-sql-connectors/cloud-sql-proxy
Each image is tagged with the associated Proxy version. The following tags are currently supported:
$VERSION(default)$VERSION-alpine$VERSION-buster$VERSION-bullseye
The $VERSION is the Proxy version without the leading "v" (e.g.,
2.11.3).
For example, to pull a particular version, use a command like:
# $VERSION is 2.11.3
docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.3We recommend pinning to a specific version tag and using automation with a CI pipeline to update regularly.
The default container image uses distroless with a non-root user. If you need a shell or related tools, use the Alpine or Buster images listed above.
The containers have the proxy as an ENTRYPOINT so, to use the proxy from a
container, all you need to do is specify options using the command, and expose
the 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:2.11.3 \
--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 for
connections originating from within the container.
You will need to authenticate using one of the methods outlined in the credentials section. If using a credentials file you must mount the file and ensure that the non-root user that runs the proxy has read access to the file. These alternatives might help:
- Change the group of your local file and add read permissions to the group
with
chgrp 65532 key.json && chmod g+r key.json. - If you can't control your file's group, you can directly change the public
permissions of your file by doing
chmod o+r key.json.
Warning
This can be insecure because it allows any user in the host system to read the credential file which they can use to authenticate to services in GCP.
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:2.11.3 \
--address 0.0.0.0 \
--port <proxy-port> \
--credentials-file /config/sa.json <instance-connection-name>See the example here as well as Connecting from Google Kubernetes Engine.
The Cloud SQL Auth Proxy includes support for sending requests through a SOCKS5
proxy. If a SOCKS5 proxy is running on localhost:8000, the command to start
the Cloud SQL Auth Proxy would look like:
ALL_PROXY=socks5://localhost:8000 \
HTTPS_PROXY=socks5://localhost:8000 \
cloud-sql-proxy <INSTANCE_CONNECTION_NAME>
The ALL_PROXY environment variable specifies the proxy for all TCP
traffic to and from a Cloud SQL instance. The ALL_PROXY environment variable
supports socks5 and socks5h protocols. To route DNS lookups through a proxy,
use the socks5h protocol.
The HTTPS_PROXY (or HTTP_PROXY) specifies the proxy for all HTTP(S) traffic
to the SQL Admin API. Specifying HTTPS_PROXY or HTTP_PROXY is only necessary
when you want to proxy this traffic. Otherwise, it is optional. See
http.ProxyFromEnvironment
for possible values.
The Proxy supports Cloud Monitoring, Cloud Trace, and Prometheus.
Supported metrics include:
cloudsqlconn/dial_latency: The distribution of dialer latencies (ms)cloudsqlconn/open_connections: The current number of open Cloud SQL connectionscloudsqlconn/dial_failure_count: The number of failed dial attemptscloudsqlconn/refresh_success_count: The number of successful certificate refresh operationscloudsqlconn/refresh_failure_count: The number of failed refresh operations.
Supported traces include:
cloud.google.com/go/cloudsqlconn.Dial: The dial operation including refreshing an ephemeral certificate and connecting the instancecloud.google.com/go/cloudsqlconn/internal.InstanceInfo: The call to retrieve instance metadata (e.g., database engine type, IP address, etc)cloud.google.com/go/cloudsqlconn/internal.Connect: The connection attempt using the ephemeral certificate- SQL Admin API client operations
To enable Cloud Monitoring and Cloud Trace, use the --telemetry-project flag
with the project where you want to view metrics and traces. To configure the
metrics prefix used by Cloud Monitoring, use the --telemetry-prefix flag. When
enabling telemetry, both Cloud Monitoring and Cloud Trace are enabled. To
disable Cloud Monitoring, use --disable-metrics. To disable Cloud Trace, use
--disable-traces.
To enable Prometheus, use the --prometheus flag. This will start an HTTP
server on localhost with a /metrics endpoint. The Prometheus namespace may
optionally 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 debug
logs, but if you are surprised by the Proxy's behavior, debug logging should
provide insight into internal operations and can help when reporting issues.
The Proxy includes support for an admin server on localhost. By default, the the 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 the documentation on pprof for details on how to use the profiler.
When --quitquitquit is set, the admin server adds an endpoint at /quitquitquit. The admin server exits gracefully when it receives a POST request at /quitquitquit.
The Proxy is a convenient way to control access to your database using IAM permissions while ensuring a secure connection to your Cloud SQL instance. When using the Proxy, you do not have to manage database client certificates, configured Authorized Networks, or ensure clients connect securely. The Proxy handles all of this for you.
The Proxy is a gateway to your Cloud SQL instance. Clients connect to the Proxy over an unencrypted connection and are authorized using the environment's IAM principal. The Proxy then encrypts the connection to your Cloud SQL instance.
Because client connections are not encrypted and authorized using the environment's IAM principal, we recommend running the Proxy on the same VM or Kubernetes pod as your application and using the Proxy's default behavior of allowing connections from only the local network interface. This is the most secure configuration: unencrypted traffic does not leave the VM, and only connections 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 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.
We recommend deploying the Proxy on the host machines that are running the application. However, large deployments may exceed the request quota for the SQL Admin API . If your Proxy reports request quota errors, we recommend deploying the Proxy with a connection pooler like pgbouncer or ProxySQL. For details, see Running the Cloud SQL Proxy as a Service.
Instead of using a single Proxy across multiple applications, we recommend using one Proxy instance for every application process. The Proxy uses the context's IAM principal and so have a 1-to-1 mapping between application and IAM principal is best. If multiple applications use the same Proxy instance, then it becomes unclear from an IAM perspective which principal is doing what.
After downloading a binary from the releases page, copy the sha256sum value that 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 -cFor example, after downloading the v2.1.0 release of the Linux AMD64 Proxy, you would run:
$ echo "547b24faf0dfe5e3d16bbc9f751dfa6b34dfd5e83f618f43a2988283de5208f2 *cloud-sql-proxy" | shasum -c
cloud-sql-proxy: OKIf you see OK, 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 uses semantic versioning, and uses the following lifecycle regarding support for a major version:
-
Active - Active versions get all new features and security fixes (that wouldn’t otherwise introduce a breaking change). New major versions are guaranteed to be "active" for a minimum of 1 year.
-
Maintenance - Maintenance versions continue to receive security and critical bug fixes, but do not receive new features.
The Cloud SQL Auth Proxy aims for a minimum monthly release cadence. If no new features or fixes have been added, a new PATCH version with the latest dependencies is released.
We support releases for 1 year from the release date.
Contributions are welcome. Please, see the CONTRIBUTING document for 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. See Contributor Code of Conduct for more information.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "github-actions[bot]")
![google-cloud-policy-bot[bot] avatar](https://avatars.githubusercontent.com/in/105725?v=4 "google-cloud-policy-bot[bot]")
![release-please[bot] avatar](https://avatars.githubusercontent.com/in/40688?v=4 "release-please[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent