Connecting psql client using the Cloud SQL Proxy

This page describes how to connect a psql client to your Cloud SQL instance using the Cloud SQL Proxy, rather than over IP.

For information about connecting a psql client to a Cloud SQL instance using IP, see Connecting psql Client Using IP Addresses.

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:

Connecting the psql client

Connecting a psql to your Cloud SQL instance with the proxy involves the following steps:

  1. Enable the Cloud SQL Admin API
  2. Install the proxy
  3. Create a service account
  4. Start the proxy
  5. Start the psql session

1. Enable the API

Enable the Cloud SQL Admin API.

Enable the API

2. Install the proxy

Linux 64-bit

  1. Download the proxy: 
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
  2. Make the proxy executable: 
    chmod +x cloud_sql_proxy

Linux 32-bit

  1. Download the proxy: 
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
  2. Make the proxy executable: 
    chmod +x cloud_sql_proxy

macOS 64-bit

  1. Download the proxy: 
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
  2. Make the proxy executable: 
    chmod +x cloud_sql_proxy

macOS 32-bit

  1. Download the proxy: 
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
  2. 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 to cloud_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 to cloud_sql_proxy.exe.
If your operating system isn't included here, you can also compile the proxy from source.

3. Create a service account

When you connect using the proxy, the proxy needs to authenticate with Google Cloud Platform. You can either use your Cloud SDK credentials, or you can provide the proxy with a path to a local key file from a service account you create (recommended for production instances). If you are using your Cloud SDK credentials, you can skip this step.

For more information about service accounts, see the Google Cloud Platform Auth Guide.

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 includes the 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.

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

    Go to the Service accounts page

  2. 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 one of the following roles:
    • Cloud SQL > Cloud SQL Client
    • Cloud SQL > Cloud SQL Editor
    • Cloud SQL > Cloud SQL Admin

    Alternatively, you can use the primitive 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.

  6. Change the Service account ID to a unique, easily recognizable value.
  7. Click Furnish a new private key and confirm that the key type is JSON.
  8. Click Create.

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

4. Start the proxy

Depending on your language and environment, you can start the proxy using either TCP sockets or Unix sockets.

TCP sockets

  1. Copy your instance connection name from the Instance details page.

    For example: myproject:myregion:myinstance.

  2. 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.
  3. 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 explicit instance specification (recommended for production environments): 
      ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=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.

Unix sockets

  1. If you are using explicit instance specification, copy your instance connection name from the Instance details page.
  2. Create the directory where the proxy sockets will live: 
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  3. 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.
  4. Open a new terminal window and start the proxy.

    Some possible proxy invocation strings:

    • Using a service account and explicit instance specification (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.

  5. When using a unix socket to connect to Cloud SQL using the Cloud SQL Proxy, make sure the socket filename's length does not surpass the system's limit. 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"

5. Start the client session

Now that you have installed and started the proxy, you can start a psql session using the proxy. This command can be used whenever you want to connect to your Cloud SQL instance with a psql client.

The connection string you use depends on whether you started the proxy using a TCP socket or a UNIX socket.

TCP sockets

  1. Start the psql client: 
    psql "host=127.0.0.1 sslmode=disable dbname=<DB_NAME> user=<USER_NAME>"

    Even though the sslmode parameter is set to disable, the proxy does provide an encrypted connection.

    When you connect using TCP sockets, the proxy is accessed through 127.0.0.1.

  2. If prompted, enter the password.
  3. You should see the psql prompt.

Unix sockets

  1. Start the psql client: 
    psql "sslmode=disable host=/cloudsql/<INSTANCE_CONNECTION_NAME> user=<USERNAME>"

    Even though the sslmode parameter is set to disable, the proxy does provide an encrypted connection.

  2. Enter the password.
  3. You should see the psql prompt.

Need help? For help troubleshooting the proxy, see Troubleshooting Cloud SQL Proxy connections. Or, see our Cloud SQL Support page.

What's next