Connecting psql Client Using IP Addresses

This page describes how to connect a psql client, either running locally on your client machine or in the Cloud Shell, to your Google Cloud SQL instance over IP.

Before you begin

Before you can start using the psql client you must have:

Using a local psql client

Using a local psql client to connect to your Cloud SQL instance involves three high-level tasks:

  1. Install the psql client
  2. Configure access to your Cloud SQL instance
  3. Connect to your Cloud SQL instance

Install the psql client

To install the psql client:

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

  1. Download the PostgreSQL Core Distribution for your platform from the PostgreSQL Downloads page.
    The Core Distribution includes the psql client.
  2. Install the PostgreSQL database, following the directions on the download page.

Configure access to your Cloud SQL instance

To configure access to your instance:

  1. Go to the Cloud SQL Instances page in the Google Cloud Platform Console.

    Go to the Cloud SQL Instances page

  2. Click the instance to open its Overview page, and record its IPv4 address.
  3. Log in to the client machine where your psql client is installed.
  4. Click What's my IP to determine the IP address of the client machine.
  5. In the Instances page in the Google Cloud Platform Console, click the instance to open its Overview page.
  6. Select the Authorization tab.
  7. Under Authorized networks, click Add network and enter the IP address of the client machine where your client is installed.
  8. Click Done, then click Save at the bottom of your page to save your changes.
  9. Connect to your instance, either with SSL or without SSL.

Connect to your Cloud SQL instance without encryption

To connect to your instance:

  1. Install the psql client and configure access to your instance, if you have not done so already.
  2. Start the psql client:
    psql "sslmode=disable dbname=postgres user=postgres hostaddr=[INSTANCE_IP]"
    

  3. Enter your password.
  4. You should see the psql prompt.

Need help? See our Cloud SQL Support page.

Connect to your Cloud SQL instance using SSL

To connect to your instance using SSL:

  1. If you do not already have a client certificate and its corresponding private key, create a certificate by following the instructions at Creating a new client certificate.
    You should have the following three items:
    • A Certificate Authority (CA) certificate, with its text in a file called server-ca.pem.
    • A server public key certificate, with its text in a file called client-cert.pem.
    • A client private key, with its text in a file called client-key.pem.
  2. Install the psql client and configure access to your instance, if you have not done so already.
  3. Start the psql client:
    psql "sslmode=verify-full sslrootcert=server-ca.pem \
          sslcert=client-cert.pem sslkey=client-key.pem \
          hostaddr=[INSTANCE_IP] \
          host=[PROJECT_ID]:[INSTANCE_NAME] \
          user=postgres dbname=postgres"
    

    For example:

    psql "sslmode=verify-full sslrootcert=server-ca.pem \
          sslcert=client-cert.pem sslkey=client-key.pem \
          hostaddr=01.23.45.67 \
          host=myproject:myinstance \
          user=postgres dbname=postgres"
          

    The sslcert and sslkey parameters are optional.

    You might also want to create a Connection Service File to manage your connection parameters, especially if you are connecting to more than one instance. For more information, see the PostgreSQL documentation.

  4. Enter the password.
  5. You can confirm that the connection is encrypted by looking for the cipher in the connection information:
    SSL connection (cipher: ECDHE-RSA-AES128-GCM-SHA256, bits: 128)
    

Need help? See our Cloud SQL Support page.

Using the psql client in the Cloud Shell

You must have the Cloud SQL Editor role, or some role with the cloudsql.instances.update permission, to use Cloud Shell to connect to your instance.

  1. Go to the Google Cloud Platform Console.

    Go to the Google Cloud Platform Console

  2. Click the Cloud Shell icon towards the right in the tool bar.

    The Cloud Shell takes a few moments to initialize.

  3. At the Cloud Shell prompt, use the built-in psql client to connect to your Cloud SQL instance:
    gcloud sql connect [INSTANCE_ID] --user=postgres
    
  4. Enter your password.

Need help? See our Cloud SQL Support page.

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud SQL for PostgreSQL