For information about connecting a psql client to a Cloud SQL instance using public IP, see Connecting using a database client.
For more information about how the proxy works, see About the Cloud SQL Proxy.
Before you begin
Before you can connect a psql to a Cloud SQL instance, you must have:
Enabled the Cloud SQL Admin API
- Created a Cloud SQL instance, including configuring the default user.
For more information about creating instances, see Creating Instances.
For more information about configuring the default user, see Configuring the default user account.
- Installed the psql client.
- Installed and initialized the Cloud SDK.
- If needed, installed the Docker client.
Options for authenticating the Cloud SQL Proxy
All of these options use an INSTANCE_CONNECTION_NAME as the connection string to identify a Cloud SQL instance. You can find the INSTANCE_CONNECTION_NAME on the Overview page for your instance in the Google Cloud Console. or by running the following command:
gcloud sql instances describe INSTANCE_NAME
.
For example: myproject:myregion:myinstance
.
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.
The Cloud SQL Proxy provides several alternatives for authentication, depending on your environment. The proxy checks for each of the following items, in the following order, using the first one it finds to attempt to authenticate:
Credentials supplied by the credential_file flag.
Use a service account to create and download the associated JSON file, and set the-credential_file
flag to the path of the file when you start the Cloud SQL Proxy. The service account must have the required permissions for the Cloud SQL instance.To use this option on the command-line, 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
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.
Credentials supplied by an access token.
Create an access token and invoke thecloud_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
Credentials supplied by an environment variable.
This option is similar to using the-credential_file
flag, except you specify the JSON credential file you set in theGOOGLE_APPLICATION_CREDENTIALS
environment variable instead of using the-credential_file
code> command-line argument.Credentials from an authenticated Cloud SDK client.
If you have installed the cloud 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 use one of the other methods to authenticate. development environment up and running. For a production environment, If no account was selected forgcloud auth login
, the proxy checks for an account that was selected forgcloud application-default login
.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.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 environment (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 roles and permissions For more information about Google Cloud's approach to authentication, see Authentication overview.
Create a Service Account
- Go to the Service accounts page of the Google Cloud Console.
- Select the project that contains your Cloud SQL instance.
- Click Create service account.
- In the Create service account dialog, provide a descriptive name for the service account.
-
For Role, select one of the following roles:
- Cloud SQL > Cloud SQL Client
- Cloud SQL > Cloud SQL Editor
- Cloud SQL > Cloud SQL Admin
- Change the Service account ID to a unique, recognizable value.
-
Click Furnish a new private key and confirm that the key type is
JSON
. -
Click Create.
The private key file is downloaded to your machine. You can move it to another location. Keep the key file secure.
Install the Cloud SQL Proxy
Linux 64-bit
- Download the proxy:
wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
- Make the proxy executable:
chmod +x cloud_sql_proxy
Linux 32-bit
- Download the proxy:
wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
- Make the proxy executable:
chmod +x cloud_sql_proxy
macOS 64-bit
- Download the proxy:
curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
- Make the proxy executable:
chmod +x cloud_sql_proxy
macOS 32-bit
- Download the proxy:
curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
- 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 tocloud_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 tocloud_sql_proxy.exe
.
Docker proxy image
For convenience, the Cloud SQL team maintains several container images that contain the Cloud SQL Proxy for use by our customers. For more information about these images, see the Cloud SQL Proxy repo on GitHub. 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 proxy from source.Start the Cloud SQL Proxy
Depending on your language and environment, you can start the proxy using TCP sockets, Unix sockets, or the Docker proxy image. 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.
TCP sockets
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
Copy your INSTANCE_CONNECTION_NAME. This can be found on the Overview page for your instance in the Google Cloud Console. or by running the following command:
gcloud sql instances describe INSTANCE_NAME
.For example: myproject:myregion:myinstance.
- If the instance has both public and private IP configured, and you want the
proxy to use the private IP address,
you must provide the following option when you start the proxy:
-ip_address_types=PRIVATE
- If you are using a service account to authenticate the proxy, note the location on your client machine of the private key file that was created when you created the service account.
- Start the proxy.
Some possible proxy invocation strings:
- Using Cloud SDK authentication:
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:5432
The specified port must not already be in use, for example, by a local database server. - Using a service account and explicitly including the name of the instance connection
(recommended for production environments):
./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAM=tcp:5432 \ -credential_file=PATH_TO_KEY_FILE &
For more information about proxy options, see Options for authenticating the proxy and Options for specifying instances.
- Using Cloud SDK authentication:
Unix sockets
The Cloud SQL Proxy can 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.
- If you are using explicit instance specification, copy your INSTANCE_CONNECTION_NAME. This can
be found on the Overview page for your instance in the
Google Cloud Console. or by running the
following command:
gcloud sql instances describe INSTANCE_NAME
.For example: myproject:myregion:myinstance.
- Create the directory where the proxy sockets will live:
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
- If you are using a service account to authenticate the proxy, note the location on your client machine of the private key file that was created when you created the service account.
- Open a new terminal window and start the proxy.
Some possible proxy invocation strings:
- Using a service account and explicitly including the name of the instance connection
(recommended for production environments):
./cloud_sql_proxy -dir=/cloudsql -instances=INSTANCE_CONNECTION_NAME -credential_file=PATH_TO_KEY_FILE &
- Using Cloud SDK authentication and automatic instance discovery:
./cloud_sql_proxy -dir=/cloudsql &
It is best to start the proxy in its own terminal so you can monitor its output without it mixing with the output from other programs.
For more information about proxy options, see Options for authenticating the proxy and Options for specifying instances.
- Using a service account and explicitly including the name of the instance connection
(recommended for production environments):
Docker proxy image
To run the Cloud SQL Proxy in a Docker container, use the Proxy Docker image available from the Google Container Registry.
You can start the proxy using either TCP sockets or Unix sockets, with the commands shown below. The options use an INSTANCE_CONNECTION_NAME as the connection string to identify a Cloud SQL instance. You can find the INSTANCE_CONNECTION_NAME on the Overview page for your instance in the Google Cloud Console. or by running the following command:
gcloud sql instances describe INSTANCE_NAME.
For example: myproject:myregion:myinstance
.
Depending on your language and environment, you can start the proxy using either TCP sockets or Unix sockets. Unix sockets are not supported for applications written in the Java programming language or for the Windows environment.
Using TCP sockets
docker run -d \\ -v PATH_TO_KEY_FILE:/config \\ -p 127.0.0.1:5432:5432 \\ gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \\ -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:5432 -credential_file=/config
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
line.
Always specify 127.0.0.1
prefix in -p so that the proxy is not
exposed outside the local host. The "0.0.0.0" in the instances parameter
is required to make the port accessible from outside of the Docker
container.
Using Unix sockets
docker run -d -v /cloudsql:/cloudsql \\ -v PATH_TO_KEY_FILE:/config \\ gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy -dir=/cloudsql \\ -instances=INSTANCE_CONNECTION_NAME -credential_file=/config
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
line.
If you are using a container optimized image, use a writeable directory
in place of /cloudsql
, for example:
-v /mnt/stateful_partition/cloudsql:/cloudsql
You can specify more than one instance, separated by commas. You can also use Compute Engine metadata to dynamically determine the instances to connect to. Learn more about the proxy parameters.
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.
Connect to the Cloud SQL Proxy
The connection string you use depends on whether you started the proxy using a TCP socket or a UNIX socket or Docker.
TCP sockets
- Start the psql client:
psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
Even though the
sslmode
parameter is set todisable
, the proxy does provide an encrypted connection.When you connect using TCP sockets, the proxy is accessed through
127.0.0.1
. - If prompted, enter the password.
- The psql prompt appears.
Using Unix sockets
- Start the psql client:
psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME user=USERNAME"
Even though the
sslmode
parameter is set todisable
, the proxy does provide an encrypted connection. - Enter the password.
- The psql prompt appears.
Need help? For help troubleshooting the proxy, see Troubleshooting Cloud SQL Proxy connections. Or, see our Cloud SQL Support page.
Language-specific code samples
You can connect to the proxy from any language that enables you to connect to a Unix or TCP socket. Below are some code snippets from complete examples on GitHub to help you understand how they work together in your application.
Additional topics
Using the proxy with private IP
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.
The proxy uses IP to establish a connection with your Cloud SQL instance. By default, the proxy attempts to connect using a public IPv4 address. If your Cloud SQL instance has only private IP, the proxy uses the private IP address to connect.
If the instance has both public and private IP configured, and you want the proxy to use the private IP address, you must provide the following option when you start the proxy:
-ip_address_types=PRIVATE
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.19.1
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:5432:5432 \ gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \ -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:5432 \ -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.19.1 /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
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.
- 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 restarts it automatically if it stops responding. See the NSSM documentation for more information.
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. Also, the output from the proxy can help you diagnose connection problems, so it can be helpful to capture in a log file. If you do not start the proxy in the background, the output goes to stdout unless redirected.
You do not have to use /cloudsql
as the directory for the proxy sockets. (That
directory name was chosen to minimize differences with App Engine
connection strings.) If you change the directory name, however, keep the overall
length to a minimum; it is incorporated in a longer string that has a length
limit imposed by the operating system. It depends on the system, but it's usually
between 91-108 characters. On Linux, the length is usually defined as 108, and
you can use the following command to check:
cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"
Using the proxy to connect to multiple instances
You can use one local proxy client to connect to multiple Cloud SQL instances. The way you do this depends on whether you are using Unix sockets or TCP.
Unix sockets
To connect the proxy to multiple instances, you provide the instance connection names with the `-instances` parameter, in a comma-separated list (no spaces). The proxy connects to each instance when it starts.
You connect to each instance using its socket, in the specified directory.
For example:
./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance,myProject:us-central1:myInstance2 & psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2
TCP sockets
When you connect using TCP, you specify the port on your machine to use to connect to the instance, and every instance must have its own port. The psql tool uses 5432 by default, but you can specify another port for it to use.
For example:
# Start the proxy for two instances, each with its own port: ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:5432,myProject:us-central1:myInstance2=tcp:1234 # Connect to "myInstance" on port 5432, and "myInstance2" on port 1234 psql -U myUser -h 127.0.0.1 --port 5432 psql -U myUser -h 127.0.0.1 --port 1234
Proxy invocations and psql client connection strings
You can use proxy invocations and connection strings, for example, in commands
for a PostgreSQL user myUser
, for the myInstance
instance, located in
us-central1
, in the myProject
project.
./cloud_sql_proxy -dir=/cloudsql & psql -U myUser -h /cloudsql/myProject:us-central1:myInstanceUsing project discovery with gcloud credentials:
./cloud_sql_proxy -dir=/cloudsql -projects=myProject & psql -U myUser -h /cloudsql/myProject:us-central1:myInstanceFor a Compute Engine instance, with explicit instance specification:
./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance & psql -U myUser -h /cloudsql/myProject:us-central1:myInstanceFor Unix, using TCP:
./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:5432 & psql -U myUser -h 127.0.0.1For Windows (at the command line prompt):
cloud_sql_proxy.exe -instances=myProject:us-central1:myInstance=tcp:5432 psql -U myUser -h 127.0.0.1
For more information about Cloud SQL Proxy options and connection strings, see the Cloud SQL Proxy GitHub page.
Troubleshooting Cloud SQL Proxy connections
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.
If you are having trouble connecting to your Cloud SQL instance using the Cloud SQL Proxy, here are a few things to try to find what's causing the problem.
Check the proxy output.
Often, the proxy output can help you determine the source of the problem and how to solve it. Pipe the output to a file, or watch the terminal where you started the proxy.
If you are getting a
403 notAuthorized
error, and you are using a service account to authenticate the proxy, make sure the service account has the correct permissions.You can check the service account by searching for its ID on the IAM page. It must have the
cloudsql.instances.connect
permission. All Cloud SQL predefined roles have this permission, except forCloud SQL Viewer
. In addition, the legacy project roles ofEditor
andOwner
have the required permission.Make sure to enable the Cloud SQL Admin API.
If it is not, you see output like
Error 403: Access Not Configured
in your proxy logs.If you are including multiple instances in your instances list, make sure you are using a comma as a delimiter, with no spaces. If you are using TCP, make sure you are specifying different ports for each instance.
If you are connecting using UNIX sockets, confirm that the sockets were created by listing the directory you provided when you started the proxy.
If you have an outbound firewall policy, make sure it allows connections to port 3307 on the target Cloud SQL instance.
What's next
- Learn more about the proxy.
- Learn more about Identity and Access Management (IAM).
- Learn more about Service Accounts.
- Learn about the two levels of access control for Cloud SQL instances.
- Create users and databases.
- Learn about connecting to your instance from your application.
- Learn about the psql Client.
- Learn about options for support.