About the Cloud SQL Proxy

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

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

What the proxy provides

The Cloud SQL Proxy provides secure access to your Cloud SQL Second Generation instances without having to whitelist IP addresses or configure SSL. You can use the proxy from any client that supports the MySQL Client/Server Protocol.

Accessing your Cloud SQL instance using the Cloud SQL Proxy offers these advantages:

  • Secure connections: The proxy automatically encrypts traffic to and from the database; SSL certificates are used to verify client and server identities.
  • Easier connection management: The proxy handles authentication with Google Cloud SQL, removing the need to provide static IP addresses.

The proxy uses the Cloud SQL API to authenticate with the Google Cloud Platform; you must enable the API before using the proxy. You must also provide the proxy with a valid user account.

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

Diagram of the proxy connecting from client software to SQL instance

Options for authenticating the Cloud SQL Proxy

The Cloud SQL Proxy provides several alternatives for authentication, depending on your environment. The proxy checks for each of the following items, in this order, using the first one it finds to attempt to authenticate:

  1. Credentials supplied in the proxy invocation command
  2. Credentials supplied by the local environment
  3. Credentials associated with the Compute Engine instance
  4. Credentials from an authenticated Cloud SDK client

See sample invocations and connection strings.

Credentials supplied in the proxy invocation command

You can create a credential file using the Google Cloud Platform Console and provide it on the command line when you start the Cloud SQL Proxy with the -credential_file parameter. The service account must have the required permissions for the Cloud SQL instance.

The advantage of this authentication method is that you can create a credential file specifically for the proxy, and it is explicitly and permanently linked to the proxy as long as it is running. For this reason, this 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 Proxy from multiple machines.

To use this method, you must create and manage the credential file. For information about creating a credential file, see Creating a service account.

Credentials supplied by the local environment

This method is identical to supplying a credential file on the command line, except that the location of the credential file is supplied using the GOOGLE_APPLICATION_CREDENTIALS environment variable.

Credentials associated with the Compute Engine instance

If you are connecting to Cloud SQL from a Compute Engine instance, the proxy can use the service account associated with the Compute Engine instance. If the service account has the required permissions for the Cloud SQL instance, the proxy authenticates successfully.

If the Compute Engine instance is in the same project as the Cloud SQL instance, the default service account for the Compute Engine instance has the necessary permissions for authenticating the proxy. If the two instances are in different projects, you must add the Compute Engine instance's service account to the project containing the Cloud SQL instance.

Credentials from an authenticated Cloud SDK client

If you have installed the Cloud SDK and used it to authenticate to the Google Cloud Platform, the Cloud SQL Proxy can use the same credentials. This method is especially helpful for getting a development environment up and running quickly. For a production environment, you should use one of the other methods to authenticate.

You can determine what your current Cloud SDK credentials are by using the gcloud auth list command.

Required permissions for service accounts

When you use a service account to provide the credentials for the 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 the Cloud SQL Client role.

If you are using the legacy 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 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 proxy ahead of time which instances you want to connect to, because the proxy connects based on connection requests.

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

Option Benefits Caveats and Requirements Linux/OS X
(Unix sockets)
Java Windows Notes
FUSE
(Filesystem in User Space)
Dynamic socket creation based on connection requests; no proxy restarts needed as instances change. FUSE must be installed. Supported No No Use -fuse flag.
Automatic instance discovery No need to specify instances; sockets created for all instances in default project. Proxy API usage is increased. Must have Cloud SDK installed and authenticated, with a default project set. Must restart 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. Proxy API usage is increased. Must have Cloud SDK installed and authenticated. Must restart proxy to add new instance. Supported No No Use -projects parameter. Not recommended for production instances.
Instances specified on proxy invocation Instance list known and static. Must restart 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.
Instances specified using Compute Engine metadata Instance list can be updated by changing the metadata value without restarting the 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.

Tips for working with Cloud SQL Proxy

Invoking the Cloud SQL Proxy

All of the example proxy invocations start the proxy in the background, so a prompt is returned. It is preferable to reserve that terminal for the proxy, to avoid having its output mixed with the output from other programs.

API usage

The Cloud SQL Proxy issues requests to the Cloud SQL API. If you are using automatic instance discovery or the -projects parameter, the proxy's API usage is increased, in some cases significantly. These requests count against the API quota for your project. This is one reason why you should not use automatic instance discovery or the -projects parameter in production.

About creating a special user account for the proxy

When you connect to your instance using the proxy, you provide a user account that is used 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 for proxy connections, 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. For information about MySQL user accounts, see Securing the Initial MySQL Accounts in the MySQL Documentation.

Cloud SQL Proxy parameters and flags

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

For help with proxy options, see the following information:

Example proxy invocations and mysql client connection strings

The instance connection name is listed in the instance properties in the Google Cloud Platform Console.

Using FUSE and a local credentials key file:

./cloud_sql_proxy -dir=/cloudsql -fuse  -credential_file=[PATH_TO_KEY_FILE] &
mysql -u [USER_NAME] -S /cloudsql/[INSTANCE_CONNECTION_NAME]
Using automatic instance discovery with gcloud credentials:

./cloud_sql_proxy -dir=/cloudsql &
mysql -u [USER_NAME] -S /cloudsql/[INSTANCE_CONNECTION_NAME]
Using project discovery with gcloud credentials:

./cloud_sql_proxy -dir=/cloudsql -projects=[PROJECT-ID]&
mysql -u [USER_NAME] -S /cloudsql/[INSTANCE_CONNECTION_NAME]
For a Google Compute Engine instance, with explicit instance specification:

./cloud_sql_proxy -dir=/cloudsql -instances=[INSTANCE_CONNECTION_NAME] &
mysql -u [USER_NAME] -S /cloudsql/[INSTANCE_CONNECTION_NAME]
For Unix, using TCP:

./cloud_sql_proxy -instances=[INSTANCE_CONNECTION_NAME]=tcp:3306 &
mysql -u [USER_NAME] --host 127.0.0.1
For Windows (at the command line prompt):

cloud_sql_proxy.exe -instances=[INSTANCE_CONNECTION_NAME]=tcp:3306
mysql -u [USER_NAME] --host 127.0.0.1

For more information about Cloud SQL Proxy options and connection strings, see the Cloud SQL Proxy GitHub page.

How FUSE is used with Cloud SQL Proxy

FUSE stands for "Filesystem in User Space". Depending on how the Cloud SQL Proxy is invoked, it can optionally use FUSE to create the sockets it uses to connect with Cloud SQL.

When connecting from Compute Engine or local development environments, the Cloud SQL Proxy uses FUSE to access Cloud SQL instances as follows:

  • The “/cloudsql” directory is mounted as a Filesystem in Userspace, or FUSE, by Cloud SQL Proxy.

  • A process (for example, mysql) attempts to lookup a file named $INSTANCE.

  • The proxy intercepts the request and returns that “/cloudsql/$INSTANCE” is a symbolic link pointing to a Unix socket located elsewhere on the filesystem.

  • The process (for example, mysql) follows the link and opens the Unix socket that it leads to and proxying proceeds.

Installing FUSE

For Linux:

FUSE requires the fusermount program, and a kernel module, to function. You can check to see if this program is installed by looking for the file, /dev/fuse/. If fusermount isn't on your system, you can install it using your package manager or compiling it from source.

For OS X:

Install OS X FUSE.

Creating a service account

To create a service account:

  1. Go to the Cloud SQL Service accounts page of the Google Cloud Platform Console.

    Go to the Service accounts page

  2. If needed, select the project that contains your Cloud SQL instance.
  3. Click Create service account.
  4. In the Create service account dialog, provide a descriptive name for the service account.
  5. For Role, select Cloud SQL > Cloud SQL Client.

    Alternatively, you can use the primitive Editor role by selecting Roles > Editor, but the Editor role includes permissions across Google Cloud Platform.

  6. Change the Service account ID to a shorter value if needed.
  7. Click Furnish a new private key.
  8. The default key type is JSON, the correct value.
  9. Click Create.

    The private key file is downloaded to your machine. You can move it to another location. Keep the key file secure.

For more information about service accounts, see User accounts and service accounts.

What's next

Send feedback about...

Cloud SQL for MySQL