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:
- Quickstart for using the Cloud SQL Auth proxy
- How to connect using the Cloud SQL Auth proxy
- How to connect using the Cloud SQL Auth proxy from GKE
Try it for yourself
If you're new to Google Cloud, create an account to evaluate how Cloud SQL performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.Try Cloud SQL free
What the Cloud SQL Auth proxy provides
Accessing your Cloud SQL instance using the Cloud SQL Auth proxy offers the following advantages:
- Secure connections: The Cloud SQL Auth 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 Cloud SQL Auth proxy handles authentication with Cloud SQL, removing the need to provide static IP addresses.
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.
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:
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).
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.
cloud_sql_proxy executable with the argument
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 authentication. 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
(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.
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 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
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
(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.||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||
|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||
|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||
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.
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.
About creating a special user account for the Cloud SQL Auth proxy
When you connect to your instance using the Cloud SQL Auth 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 Cloud SQL Auth proxy always connects from a hostname that cannot be accessed except by the Cloud SQL Auth proxy, you can create a user account that can be used only by the Cloud SQL Auth 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 Cloud SQL Auth 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 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:
- Options for authenticating the Cloud SQL Auth proxy
- Options for specifying Cloud SQL instances
- Example Cloud SQL Auth proxy invocations
- Cloud SQL Auth proxy GitHub page
- The Cloud SQL Auth proxy help, displayed with
How FUSE is used with Cloud SQL Auth proxy
When connecting from Compute Engine or local development environments, the Cloud SQL Auth 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 Auth proxy.
A process (for example,
mysql) attempts to lookup a file named $INSTANCE.
The Cloud SQL Auth proxy intercepts the request and returns that
/cloudsql/$INSTANCEis 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 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
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
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.