About the Cloud SQL Auth proxy

This page provides a basic introduction to the Cloud SQL Auth proxy, and describes the proxy options.

For step-by-step instructions on using the Cloud SQL Auth proxy, follow the link for your environment:

You do not need to use the Cloud SQL Auth proxy or configure SSL to connect to Cloud SQL from App Engine standard environment or App Engine flexible environment.

What the Cloud SQL Auth proxy provides

The Cloud SQL Auth proxy provides secure access to your instances without a need for Authorized networks or for configuring SSL.

The Cloud SQL Auth proxy and other Cloud SQL connectors have the following advantages:

  • Secure connections: The Cloud SQL Auth proxy automatically encrypts traffic to and from the database using TLS with a 128-bit AES cipher. SSL certificates are used to verify client and server identities, and are independent of database protocols; you won't need to manage SSL certificates.
  • Easier connection authorization: The Cloud SQL Auth proxy uses IAM permissions to control who and what can connect to your Cloud SQL instances. Thus, the Cloud SQL Auth proxy handles authentication with Cloud SQL, removing the need to provide static IP addresses.
  • IAM database authentication. Optionally, the Cloud SQL Auth proxy supports an automatic refresh of OAuth 2.0 access tokens. For information about this functionality, see Cloud SQL IAM database authentication.

The Cloud SQL Auth proxy does not provide a new connectivity path; it relies on existing IP connectivity. 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.

How the Cloud SQL Auth proxy works

The Cloud SQL Auth proxy works by having a local client running in the local environment. Your application communicates with the Cloud SQL Auth proxy with the standard database protocol used by your database. The Cloud SQL Auth proxy uses a secure tunnel to communicate with its companion process running on the server. Each connection established through the Cloud SQL Auth proxy creates one connection to the Cloud SQL instance. The Cloud SQL Auth proxy doesn't provide connection pooling, but can be paired with other connection pooling to increase efficiency.

While the Cloud SQL Auth proxy can listen on any port, it only creates outgoing connections to your Cloud SQL instance on port 3307. If your client machine has an outbound firewall policy, make sure it allows outgoing connections to port 3307 on your Cloud SQL instance's IP.

The following diagram shows how the Cloud SQL Auth proxy connects to Cloud SQL:

Diagram of the Cloud SQL Auth proxy connecting from client software to SQL instance

Requirements for using the Cloud SQL Auth proxy

To use the Cloud SQL Auth proxy, you must meet the following requirements:

  • The Cloud SQL Admin API must be enabled.
  • You must provide the Cloud SQL Auth proxy with Google Cloud authentication credentials.
  • You must provide the Cloud SQL Auth proxy with a valid database user account and password.

  • The instance must either have a public IPv4 address, or be configured to use private IP.

    The public IP address does not need to be accessible to any external address (it does not need to be added as an authorized network address).

Download and install the Cloud SQL Auth proxy

Linux 64-bit

  1. Download the Cloud SQL Auth proxy: 
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
  2. Make the Cloud SQL Auth proxy executable: 
    chmod +x cloud_sql_proxy

Linux 32-bit

  1. Download the Cloud SQL Auth proxy: 
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
  2. If the wget command is not found, run sudo apt-get install wget and repeat the download command.
  3. Make the Cloud SQL Auth proxy executable: 
    chmod +x cloud_sql_proxy

macOS 64-bit

  1. Download the Cloud SQL Auth proxy: 
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
  2. Make the Cloud SQL Auth proxy executable: 
    chmod +x cloud_sql_proxy

macOS 32-bit

  1. Download the Cloud SQL Auth proxy: 
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
  2. 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, several container images that contain the Cloud SQL Auth proxy are available on GitHub in the Cloud SQL Auth proxy repo. 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.19.1

Other OS

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

Cloud SQL Auth proxy startup options

When you start the Cloud SQL Auth proxy, you provide it with the following information:

  • What Cloud SQL instances to establish connections to
  • Where it will listen for data coming from your application to be sent to Cloud SQL
  • Where it will find the credentials it will use to authenticate your application to Cloud SQL
  • If required, which IP address type to use.

The Cloud SQL Auth proxy startup options you provide determine whether it will listen on a TCP port or on a Unix socket. If it is listening on a Unix socket, it creates the socket at the location you choose; usually, the /cloudsql/ directory. For TCP, the Cloud SQL Auth proxy listens on localhost by default.

Run the cloud_sql_proxy executable with the argument --help to view the complete list of startup options.

You can install the Cloud SQL Auth proxy anywhere in your local environment. The location of the Cloud SQL Auth proxy binaries does not impact where it listens for data from your application.

Using a service account for authentication

The Cloud SQL Auth proxy requires authenticating as a Cloud SQL IAM identity to authorize your connections to a Cloud SQL instance.

The advantage of using a service account for this purpose is that you can create a credential file specifically for the Cloud SQL Auth proxy, and it is explicitly and permanently linked to the Cloud SQL Auth proxy as long as it is running. For this reason, using a service account is the recommended method for production instances not running on a Compute Engine instance.

The credential file can be duplicated in a system image if you need to invoke the Cloud SQL Auth proxy from multiple machines.

To use this method, you must create and manage the credential file. Only users with the resourcemanager.projects.setIamPolicy permission (such as project owners) can create the service account. If your Google Cloud user does not have this permission, you must have someone else create the service account for you, or use another method to authenticate the Cloud SQL Auth proxy.

Learn how to Create a service account.

Required permissions for service accounts

When you use a service account to provide the credentials for the Cloud SQL Auth proxy, you must create it with sufficient permissions. If you are using the finer-grained Identity Access and Management (IAM) roles to manage your Cloud SQL permissions, you must give the service account a role that includes the cloudsql.instances.connect permission. The predefined Cloud SQL roles that include this permission are:

  • Cloud SQL Client
  • Cloud SQL Editor
  • Cloud SQL Admin

If you are using the legacy project roles (Viewer, Editor, Owner), the service account must have at least the Editor role.

Options for specifying Cloud SQL instances

There are several ways to tell the Cloud SQL Auth proxy which instances you want to connect to. Some are explicit and some are implicit. In some configurations, you do not have to tell the Cloud SQL Auth proxy ahead of time which instances you want to connect to, because the Cloud SQL Auth proxy connects based on connection requests.

Your options for instance specification depend on your operating system and environment:

Option Benefits Caveats and Requirements Linux/macOS
(Unix sockets)		 Java Windows Notes
Automatic instance discovery No need to specify instances; sockets created for all instances in default project. Cloud SQL Auth proxy API usage is increased. Must have Cloud SDK installed and authenticated, with a default project set. Must restart Cloud SQL Auth proxy to add new instance. Supported No No Not recommended for production instances.
Project discovery No need to specify instances; sockets created for all instances in specified projects. Cloud SQL Auth proxy API usage is increased. Must have Cloud SDK installed and authenticated. Must restart Cloud SQL Auth proxy to add new instance. Supported No No Use -projects parameter. Not recommended for production instances.
Instances specified on Cloud SQL Auth proxy invocation Instance list known and static. Must restart Cloud SQL Auth proxy to add new instance. Supported Supported with TCP sockets Supported with TCP sockets Use -instances parameter. For multiple instances, use a comma-separated list, with no spaces. Learn more.
Instances specified using Compute Engine metadata Instance list can be updated by changing the metadata value without restarting the Cloud SQL Auth proxy. Available only on Compute Engine. Supported Supported with TCP sockets Supported with TCP sockets Use -instances_metadata flag. Learn more.
See sample invocations and connection strings.

Keeping the Cloud SQL Auth proxy up-to-date

Google occasionally releases new versions of the Cloud SQL Auth proxy. You can see what the current version is by checking the Cloud SQL Auth proxy GitHub releases page. Future proxy releases will also be noted in the Google Groups Cloud SQL announce forum.

API usage

The Cloud SQL Auth proxy issues requests to the Cloud SQL Admin API. These requests count against the API quota for your project.

The highest API usage occurs when you start the Cloud SQL Auth proxy; this is especially true if you use automatic instance discovery or the -projects parameter. While the Cloud SQL Auth proxy is running, it issues 2 API calls per hour per connected instance.

Cloud SQL Auth proxy parameters and flags

The Cloud SQL Auth proxy accepts several flags and parameters when it is started. These options determine where and how the Cloud SQL Auth proxy creates the sockets it uses for communicating with Cloud SQL, and how it authenticates.

For help with Cloud SQL Auth proxy options, see the following information:

Using the Cloud SQL Auth proxy in a production environment

When you are using the Cloud SQL Auth proxy in a production environment, there are some steps you can take to ensure that the Cloud SQL Auth proxy provides the required availability for your application.

Ensure that the Cloud SQL Auth proxy is run as a persistent service

If the Cloud SQL Auth proxy process is stopped, all existing connections through it are dropped, and your application cannot create any more connections to the Cloud SQL instance with the Cloud SQL Auth proxy. To prevent this scenario, be sure to run the Cloud SQL Auth proxy as a persistent service, so that if the Cloud SQL Auth proxy exits for any reason, it is automatically restarted. This can be accomplished by using a service such as systemd, upstart, or supervisor. For the Windows operating system, run the Cloud SQL Auth proxy as a Windows Service. In general, make sure the Cloud SQL Auth proxy has the same uptime requirements as your application process.

How many copies of the Cloud SQL Auth proxy your application needs

There is no need to create a proxy process for every application process; many application processes can share a single Cloud SQL Auth proxy process. Run one Cloud SQL Auth proxy client process per workstation or virtual machine.

If you are using auto-scaling for virtual machines, ensure that the Cloud SQL Auth proxy is included in your virtual machine configuration, so that whenever a new virtual machine is started, it has its own Cloud SQL Auth proxy process.

It is up to you to manage how many connections your application requires, whether by limiting or pooling the connections. The Cloud SQL Auth proxy does not place any limitations on new connection rates or persistent connection count.

Reducing Cloud SQL Auth proxy output

If you need to reduce the size of the Cloud SQL Auth proxy log, you can do so by setting -verbose=false when you start the Cloud SQL Auth proxy. Keep in mind, however, that doing so reduces the effectiveness of the Cloud SQL Auth proxy output in diagnosing connection issues.

How failover affects the Cloud SQL Auth proxy

If you are running the Cloud SQL Auth proxy on an instance configured for High Availability, and a failover occurs, connections through the Cloud SQL Auth proxy are affected the same way as connections over IP: all existing connections are lost, and the application must establish new connections. However, no manual intervention is required; the application can continue using the same connection strings it was before.

Keeping the Cloud SQL Auth proxy Docker image up to date

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.

What's next