This page describes how to use the psql client, installed on a Compute Engine instance, to connect to Cloud SQL.
You can use private IP, public IP, the Cloud SQL Auth Proxy, or the Cloud SQL Auth Proxy Docker image.
For step-by-step instructions on running a Compute Engine sample web application connected to Cloud SQL, see the quickstart for connecting from Compute Engine.
Before you begin
This task does not include instructions for setting up your Compute Engine instance. If you need help with creating and configuring a Compute Engine instance, see the Compute Engine documentation.
Private IP
To connect to Cloud SQL from a Compute Engine instance using private IP, private services access must be set up for your environment and your Cloud SQL instance must be configured to use private IP. Your Compute Engine instance must be in the same region as your Cloud SQL instance, and on the network configured for a private connection. Learn more.
1. Configure your instance to use private IP
Use the instructions in Configuring Private IP Connectivity.
2. Open a Cloud Shell terminal connection to your Compute Engine instance.
Use the appropriate instructions, depending on the instance's operating system:
- For Linux, see Connecting to Linux VMs.
- For Windows, see Connecting to Windows VMs.
If your Compute Engine instance is running either an RHEL or a CentOS public image, SELinux might block the proxy connection. If this happens, you must configure the SELinux feature to allow the connection.
For more information about SELinux for RHEL, see the RHEL documentation. For more information about SELinux for CentOS, see the CentOS documentation.
3. Install the psql client on the Compute Engine instance, if it is not already installed.
Debian/Ubuntu
Install the psql client from the package manager:
sudo apt-get update sudo apt-get install postgresql-client
CentOS/RHEL
Install the psql client from the package manager:
sudo yum install postgresql
openSUSE
Install the psql client from the package manager:
sudo zypper install postgresql
Other platforms
- Download the PostgreSQL Core Distribution for your platform from the
PostgreSQL Downloads page.
The Core Distribution includes the psql client. - Install the PostgreSQL database, following the directions on the download page.
4. Connect with the psql client.
psql -h CLOUD_SQL_PRIVATE_IP_ADDRESS -U USERNAME
You can find the private IP address on the
Cloud SQL instances page or by running the following
gcloud
command:
gcloud sql instances list
Public IP
To connect using public IP:
1. Add a static IPv4 IP address to the Compute Engine instance, if it does not already have one.
You cannot connect to Compute Engine using IPv6. For information about adding a static IP address, see Reserving a new static external IP address in the Compute Engine documentation.
2. Authorize the static IP address of the Compute Engine instance as a network that can connect to your Cloud SQL instance.
For more information, see Configuring access for public IP connections.
3. Open a Cloud Shell terminal connection to your Compute Engine instance.
Use the appropriate instructions, depending on the instance's operating system:
- For Linux, see Connecting to Linux VMs.
- For Windows, see Connecting to Windows VMs.
If your Compute Engine instance is running either an RHEL or a CentOS public image, SELinux might block the proxy connection. If this happens, you must configure the SELinux feature to allow the connection.
For more information about SELinux for RHEL, see the RHEL documentation. For more information about SELinux for CentOS, see the CentOS documentation.
4. Install the psql client on the Compute Engine instance, if it is not already installed.
Debian/Ubuntu
Install the psql client from the package manager:
sudo apt-get update sudo apt-get install postgresql-client
CentOS/RHEL
Install the psql client from the package manager:
sudo yum install postgresql
openSUSE
Install the psql client from the package manager:
sudo zypper install postgresql
Other platforms
- Download the PostgreSQL Core Distribution for your platform from the
PostgreSQL Downloads page.
The Core Distribution includes the psql client. - Install the PostgreSQL database, following the directions on the download page.
5. Connect with the psql client.
psql -h CLOUD_SQL_PUBLIC_IP_ADDR -U USERNAME
You can find the public IP address on the
Cloud SQL instances page or by running the following
gcloud
command:
gcloud sql instances list
For an example of how to connect using SSL, see Connecting with SSL.
6. The psql prompt appears.
7. If you need to keep unused connections alive:
Set the TCP keepalive.
For more information, see Communicating between your instances and the Internet in the Compute Engine documentation.
Connections are kept alive automatically for instances.
Cloud SQL Auth Proxy
To connect using the Cloud SQL Auth Proxy from Compute Engine:1. Enable the Cloud SQL Admin API.
2. Create a service account.
- In the Google Cloud console, go to the Service accounts page.
- Select the project that contains your Cloud SQL instance.
- Click Create service account.
- In the Service account name field, enter a descriptive name for the service account.
- Change the Service account ID to a unique, recognizable value and then click Create and continue.
-
Click the Select a role field and select one of the following roles:
- Cloud SQL > Cloud SQL Client
- Cloud SQL > Cloud SQL Editor
- Cloud SQL > Cloud SQL Admin
- Click Done to finish creating the service account.
- Click the action menu for your new service account and then select Manage keys.
- Click the Add key drop-down menu and then click Create new key.
-
Confirm that the key type is JSON and then click Create.
The private key file is downloaded to your machine. You can move it to another location. Keep the key file secure.
If the Compute Engine instance is in a different project than the Cloud SQL instance, ensure that its service account has the proper permissions in the project that contains the Cloud SQL instance:
- Go to the Compute Engine instances listing in the Google Cloud console.
- If needed, select the project associated with the Compute Engine instance.
- Select the Compute Engine instance to display its properties.
- In the Compute Engine instance properties, copy the name of the service account.
- Go to the IAM & Admin Projects page in the Google Cloud console.
- Select the project that contains the Cloud SQL instance.
- Search for the service account name.
-
If the service account is already there, and it has a role that includes the
cloudsql.instances.connect
permission, you can proceed to step 4.The
Cloud SQL Client
,Cloud SQL Editor
andCloud SQL Admin
roles all provide the necessary permission, as do the legacyEditor
andOwner
project roles. - Otherwise, add the service account by clicking Add.
In the Add principals dialog, provide the name of the service account and select a role that include the
cloudsql.instances.connect
permission (any Cloud SQL predefined role other than Viewer will work).Alternatively, you can use the basic Editor role by selecting Project > Editor, but the Editor role includes permissions across Google Cloud.
If you do not see these roles, your Google Cloud user might not have the
resourcemanager.projects.setIamPolicy
permission. You can check your permissions by going to the IAM page in the Google Cloud console and searching for your user id.- Click Add.
You now see the service account listed with the specified role.
3. Open a terminal connection to your Compute Engine instance.
Use the appropriate instructions, depending on the instance's operating system:
- For Linux, see Connecting to Linux Instances.
- For Windows, see Connecting to Windows Instances.
If your Compute Engine instance is running either an RHEL or a CentOS public image, SELinux might block the proxy connection. If this happens, you must configure the SELinux feature to allow the connection.
For more information about SELinux for RHEL, see the RHEL documentation. For more information about SELinux for CentOS, see the CentOS documentation.
4. Install the psql client on the Compute Engine instance, if it is not already installed.
Debian/Ubuntu
Install the psql client from the package manager:
sudo apt-get update sudo apt-get install postgresql-client
CentOS/RHEL
Install the psql client from the package manager:
sudo yum install postgresql
openSUSE
Install the psql client from the package manager:
sudo zypper install postgresql
Other platforms
- Download the PostgreSQL Core Distribution for your platform from the
PostgreSQL Downloads page.
The Core Distribution includes the psql client. - Install the PostgreSQL database, following the directions on the download page.
5. Install the Cloud SQL Auth Proxy on the Compute Engine instance.
Linux 64-bit
- Download the Cloud SQL Auth Proxy:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.0/cloud-sql-proxy.linux.amd64
- Make the Cloud SQL Auth Proxy executable:
chmod +x cloud-sql-proxy
Linux 32-bit
- Download the Cloud SQL Auth Proxy:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.0/cloud-sql-proxy.linux.386
- If the
curl
command is not found, runsudo apt install curl
and repeat the download command. - Make the Cloud SQL Auth Proxy executable:
chmod +x cloud-sql-proxy
Windows 64-bit
Right-click https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.0/cloud-sql-proxy.x64.exe and select Save Link As to download the Cloud SQL Auth Proxy. Rename the file tocloud-sql-proxy.exe
.
Windows 32-bit
Right-click https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.0/cloud-sql-proxy.x86.exe and select Save Link As to download the Cloud SQL Auth Proxy. Rename the file tocloud-sql-proxy.exe
.
Cloud SQL Auth Proxy Docker image
The Cloud SQL Auth Proxy has different container images, such as distroless
, alpine
,
and buster
. The default Cloud SQL Auth Proxy container image uses
distroless
, which
contains no shell. If you need a shell or related tools, then download an image based on
alpine
or buster
.
For more information, see
Cloud SQL Auth Proxy Container Images.
You can pull the latest image to your local machine using Docker by using the following command:
docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.14.0
Other OS
For other operating systems not included here, you can compile the Cloud SQL Auth Proxy from source.6. Start the Cloud SQL Auth Proxy.
Depending on your language and environment, you can start the Cloud SQL Auth Proxy using TCP sockets, Unix sockets, or the Cloud SQL Auth Proxy Docker image. The Cloud SQL Auth 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 Cloud SQL Auth Proxy listens on localhost
(127.0.0.1
) by default.
So, when you specify --port 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 Cloud SQL Auth Proxy listen at 0.0.0.0:1234
for the
local connection:
./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME
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 --format='value(connectionName)'
For example: myproject:myregion:myinstance.
- If the instance has both public and private IP configured, and you want the
Cloud SQL Auth Proxy to use the private IP address,
you must provide the following option when you start the Cloud SQL Auth Proxy:
--private-ip
- If you are using a service account to authenticate the Cloud SQL Auth Proxy, note the location on your client machine of the private key file that was created when you created the service account.
- Start the Cloud SQL Auth Proxy.
Some possible Cloud SQL Auth Proxy invocation strings:
- Using Cloud SDK authentication:
./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
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 \ --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
For more information about Cloud SQL Auth Proxy options, see Options for authenticating the Cloud SQL Auth Proxy.
- Using Cloud SDK authentication:
Unix sockets
The Cloud SQL Auth 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 Cloud SQL Auth Proxy and application must have read and write access to it.
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 --format='value(connectionName)'
For example: myproject:myregion:myinstance.
- Create the directory where the Cloud SQL Auth Proxy sockets will live:
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
- If you are using a service account to authenticate the Cloud SQL Auth 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 Cloud Shell terminal window and start the Cloud SQL Auth Proxy.
Some possible Cloud SQL Auth Proxy invocation strings:
- Using Google Cloud SDK authentication:
./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &
- Using a service account:
./cloud-sql-proxy --unix-socket /cloudsql --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
Start the Cloud SQL Auth Proxy in its own Cloud Shell terminal so you can monitor its output without it mixing with the output from other programs.
For more information about Cloud SQL Auth Proxy options, see Options for authenticating the Cloud SQL Auth Proxy.
- Using Google Cloud SDK authentication:
Docker
To run the Cloud SQL Auth Proxy in a Docker container, use the Cloud SQL Auth Proxy Docker image available from the Google Container Registry.
You can start the Cloud SQL Auth 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 Cloud SQL Auth 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:/path/to/service-account-key.json \\ -p 127.0.0.1:5432:5432 \\ gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.14.0 \\ --address 0.0.0.0 --port 5432 \\ --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME
If you're using the credentials provided by your Compute Engine instance,
don't include the --credentials-file
parameter and the
-v PATH_TO_KEY_FILE:/path/to/service-account-key.json
line.
Always specify 127.0.0.1
prefix in -p so that the Cloud SQL Auth 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:/path/to/service-account-key.json \\ gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.14.0 --unix-socket=/cloudsql \\ --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME
If you're using the credentials provided by your Compute Engine instance,
don't include the --credentials-file
parameter and the
-v PATH_TO_KEY_FILE:/path/to/service-account-key.json
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 Cloud SQL Auth Proxy parameters.
7. Start the psql session.
The connection string you use depends on whether you started the Cloud SQL Auth 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 Cloud SQL Auth Proxy does provide an encrypted connection.When you connect using TCP sockets, the Cloud SQL Auth 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 dbname=DB_NAME user=USERNAME"
Even though the
sslmode
parameter is set todisable
, the Cloud SQL Auth Proxy does provide an encrypted connection. - Enter the password.
- The psql prompt appears.
Need help? For help troubleshooting the proxy, see Troubleshooting Cloud SQL Auth Proxy connections, or see our Cloud SQL Support page.
What's next
- Get help troubleshooting connection issues for the Cloud SQL Auth Proxy.
- Create users and databases.
- Learn more about private IP.
- Learn about options for connecting to your instance from your application.
- Learn about the psql client.
- Learn about options for support.