This page provides a basic introduction to the Cloud SQL Proxy, and describes the proxy options.
For step-by-step instructions on using the Cloud SQL Proxy, follow the link for your environment:
- Quickstart for using the proxy
- How to connect using the proxy
- How to connect using the proxy from GKE
You do not need to use the proxy or configure SSL to connect to Cloud SQL from App Engine standard or connect to Cloud SQL from the App Engine flexible environment.
What the proxy provides
Accessing your Cloud SQL instance using the Cloud SQL Proxy offers the following advantages:
- Secure connections: The proxy automatically encrypts traffic to and from the database using TLS 1.2 with a 128-bit AES cipher; SSL certificates are used to verify client and server identities.
- Easier connection management: The proxy handles authentication with Cloud SQL, removing the need to provide static IP addresses.
The 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 proxy must be on a resource with access to the same VPC network as the instance.
How the Cloud SQL Proxy works
The Cloud SQL Proxy works by having a local client, called the proxy, running in the local environment. Your application communicates with the proxy with the standard database protocol used by your database. The proxy uses a secure tunnel to communicate with its companion process running on the server.
While the proxy can listen on any port, it only creates outgoing connections to your Cloud SQL instance on port 3307. If you have an outbound firewall policy, make sure it allows connections to port 3307 on your Cloud SQL instance's IP.
The following diagram shows how the proxy connects to Cloud SQL:
Requirements for using the Cloud SQL Proxy
To use the proxy, you must meet the following requirements:
- The Cloud SQL Admin API must be enabled.
- You must provide the proxy with Google Cloud authentication credentials.
- You must provide the 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).
Proxy startup options
When you start the 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 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 proxy listens on
localhost by default.
cloud_sql_proxy executable with the argument
view the complete list of startup options.
You can install the proxy anywhere in your local environment. The location of the proxy binaries does not impact where it listens for data from your application.
Using a service account for authentication
The proxy requires authentication. The advantage of using a service account for this purpose 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, 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 Proxy from multiple machines.
To use this method, you must create and manage the credential file. Only users
(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 proxy.
For help with creating a credential file, see Creating a service account.
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 a role that
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 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/macOS
(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||
|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||
|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||
|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||
Keeping the Cloud SQL Proxy up-to-date
Google occasionally releases new versions of the proxy. You can see what the current version is by checking the Cloud SQL Proxy GitHub releases page. Future proxy releases will also be noted in the Google Groups Cloud SQL announce forum.
The Cloud SQL 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 proxy; this is especially true
if you use automatic instance discovery or the
-projects parameter. While the
proxy is running, it issues 2 API calls per hour per connected instance.
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
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:
- Options for authenticating the Cloud SQL Proxy
- Options for specifying Cloud SQL instances
- Example proxy invocations
- Cloud SQL Proxy GitHub page
- The proxy help, displayed with
How FUSE is used with Cloud SQL Proxy
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 connects.
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
fusermount isn't on your system, you can install it
using your package manager or compiling it from source.
Install FUSE for macOS.
Using the Cloud SQL Proxy in a production environment
When you are using the Cloud SQL Proxy in a production environment, there are some steps you can take to ensure that the proxy provides the required availability for your application.
Ensure that the Cloud SQL Proxy is run as a persistent service
If the 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 proxy. To prevent this scenario, be sure to
run the proxy as a persistent service, so that if the proxy exits for any
reason, it is automatically restarted. This can be accomplished by using a
service such as
supervisor. For the Windows operating
system, run the proxy as a Windows Service. In general, make sure the proxy has
the same uptime requirements as your application process.
How many copies of the Cloud SQL Proxy your application needs
There is no need to create a proxy process for every application process; many application processes can share a single proxy process. Run one proxy client process per workstation or virtual machine.
If you are using auto-scaling for virtual machines, ensure that the proxy is included in your virtual machine configuration, so that whenever a new virtual machine is started, it has its own proxy process.
It is up to you to manage how many connections your application requires, whether by limiting or pooling the connections. The proxy does not place any limitations on new connection rates or persistent connection count.
Reducing Cloud SQL Proxy output
If you need to reduce the size of the proxy log, you can do so by setting
-verbose=false when you start the proxy. Keep in mind, however, that doing
so reduces the effectiveness of the proxy output in diagnosing connection
How failover affects the Cloud SQL Proxy
If you are running the proxy on an instance configured for High Availability, and a failover occurs, connections through the 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 Proxy Docker image up to date
The Proxy Docker image is based on a specific version of the Cloud SQL Proxy. When a new version of the Cloud SQL Proxy becomes available, pull the new version of the Proxy Docker image to keep your environment up to date. You can see the current version of the Cloud SQL Proxy by checking the Cloud SQL Proxy GitHub releases page.