Authorization with the Cloud SQL Proxy

This page covers how to authorize a Cloud SQL Proxy connection. For information about how to connect to Cloud SQL instances using the proxy, see Connection Overview. For detailed information about how the proxy works and tips for working with the proxy, see About the Cloud SQL Proxy.

The Cloud SQL Proxy handles authentication with Cloud SQL, providing secure access to Cloud SQL instances without the need to manage allowed IP addresses or configure SSL connections.

Before you begin

Installing the Cloud SQL Proxy

The Cloud SQL Proxy is distributed as a free download, with precompiled executables available for 32-bit and 64-bit Linux, macOS, and Windows platforms.

Linux 64-bit

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

Linux 32-bit

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

macOS 64-bit

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

macOS 32-bit

  1. Download the proxy:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. Make the 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 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 proxy. Rename the file to cloud_sql_proxy.exe.
If your operating system isn't included here, you can also compile the proxy from source.

Enabling the API and setting permissions

The Cloud SQL Proxy uses the IAM permissions of a user or service account to authenticate your connection to a Cloud SQL instance.

  1. Enable the Cloud SQL Admin API.

    Enable the API

  2. Add one or more of the required IAM roles to your user or service account:

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

    Or, you can manually assign the following IAM permissions:

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

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.

Using credentials from the Cloud SQL Proxy

Before you can launch the Cloud SQL Proxy, you need to provide user or service account credentials that the proxy can use to authenticate a connection. There are several options for how to specify which credentials are used, and the proxy checks for each option in the following order:

All of these options use an INSTANCE_CONNECTION_NAME as the connection string to identify a Cloud SQL instance. The connection string is in PROJECT_ID:REGION:INSTANCE_ID format. You can find the instance connection string listed in the instance overview page.

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. If you need to create a new credential file, go to the Service accounts page for your project in the Cloud Console, click Actions for the service account, and select Create key to download a JSON credentials file for the service account.

Credential file on the command line

To use this option, 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

Access token on the command line

Access tokens are commonly used to authorize access on behalf of a user account. For more information about how to create and use OAuth 2.0 access tokens, see Authorize requests.

To use this option, invoke the cloud_sql_proxy comment with the -token flag set to an OAuth 2.0 access token. For example:

./cloud_sql_proxy -token=ACCESS_TOKEN -instances=INSTANCE_CONNECTION_NAME

Credential file from an environment variable

This option is similar to using the -credential_file flag, except you specify the JSON credential file in the GOOGLE_APPLICATION_CREDENTIALS environment variable instead of using the -credential_file command-line argument.

Cloud SDK user credentials

If you have installed the gcloud command-line tool and have authenticated with your personal account, the Cloud SQL Proxy can use the same account credentials. This method is especially helpful for getting a development environment up and running. For a production environment, use one of the other methods to authenticate.

To authenticate the Cloud SDK, use the gcloud auth login command and select your account and log in. You can use the gcloud auth list command to verify which account is currently authenticated for the Cloud SDK.

If no account was selected for gcloud auth login, the proxy checks for an account that was selected for gcloud application-default login.

Environment's default service account

If the 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 environments (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 Enabling the API and setting permissions.

For more information about Google Cloud's approach to authentication, see Authentication overview.

Executing the Cloud SQL Proxy

The 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.

Examples of Cloud SQL Proxy command-line usage are provided below.

Configuring TCP

To connect to a Cloud SQL instance with TCP, use the -instances command line argument to specify a comma-separated list of connection strings, with each connection string followed by a TCP port number, as shown in this example:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER

For TCP connections, the 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 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

To connect to multiple instances, you can use the Cloud SQL Proxy by specifying a comma-separated list of instance connection names in the -instances argument. Each instance must have its own port number, as shown in this example:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME_1=tcp:3306,INSTANCE_CONNECTION_NAME_2=tcp:3307

Configuring a Unix socket

The Cloud SQL Proxy can also 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.

To create and use a Unix socket, the target directory must exist and both the proxy and application must have read and write access to it. To create a new directory and set the required permissions, use these commands:

sudo mkdir ~/cloudsql
sudo chmod a+rw ~/cloudsql

There are two options for specifying the socket directory when launching the proxy. One option is to use the -dir command-line argument, as shown here:

./cloud_sql_proxy -dir=PATH_TO_TARGET_FOLDER -instances=INSTANCE_CONNECTION_NAME

Alternatively, you can append the socket directory to the connection string argument:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=unix:/PATH_TO_TARGET_FOLDER

Choosing public IP or private IP

Cloud SQL instances use public IP connectivity by default, but you can also configure an instance to support private IP connectivity. Private IP uses internal IP addresses hosted in a VPC network, which are only accessible from other resources within the same VPC network. Benefits of private IP include increased security, because IP traffic is never exposed to the internet, and increased performance, because private IP offers lower latency than public IP in some scenarios.

To configure your Cloud SQL instance to use private IP, see Configuring private IP.

The proxy's -ip_address_types command-line flag specifies the preferred order of IP used when connecting to a Cloud SQL instance. The default setting is -ip_address_types=PUBLIC,PRIVATE, which means that the proxy attempts to connect with public IP first if the instance has public IP enabled, and then the proxy attempts to connect with private IP if the instance has private IP enabled. To specify that the proxy only attempts to connect with private IP, use the -ip_address_types=PRIVATE flag as shown in this example:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306 -ip_address_types=PRIVATE

Other command-line arguments

The examples above cover the most common use cases, but the Cloud SQL 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 Proxy GitHub repository for additional examples of how to use Cloud SQL Proxy command-line options.

Additional Information

Requiring the Cloud SQL Proxy for a database user account

When you connect to your instance using the proxy, you provide a user account to log in to the instance. You can use any database user account for this purpose. However, because the proxy always connects from a hostname that cannot be accessed except by the proxy, you can create a user account that can be used only by the proxy. The advantage of doing this is that you can specify this account without a password without compromising the security of your instance or your data.

To create a user account that can only be used with the Cloud SQL Proxy, specify the hostname as 'cloudsqlproxy~[IP_ADDRESS]'. You can also use the IP address wildcard, which would result in 'cloudsqlproxy~%'. The full user account name would be:

'[USER_NAME]'@'cloudsqlproxy~%'

or

'[USER_NAME]'@'cloudsqlproxy~[IP_ADDRESS]'

For help with creating a user, see Creating and Managing Users. For information about how Cloud SQL works with user accounts, see Users.

Running the proxy in a separate process

Running the Cloud SQL 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 proxy in a separate process.

Linux

On Linux or macOS, use a trailing & on the command line to launch the 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 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 Proxy in a Docker container

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

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

You can start the 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:3306:3306 \
  gcr.io/cloudsql-docker/gce-proxy:1.16 /cloud_sql_proxy \
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:3306 \
  -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.16 /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</span> line.

Running the Cloud SQL Proxy as a service

Running the 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.

Windows

The Cloud SQL 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 proxy as a Windows service, and NSSM monitors the proxy and restart it automatically if it stops responding. See the NSSM documentation for more information.

Next steps