Connect a psql client to an instance

This page describes how to connect the psql client tool to an AlloyDB instance.

The procedure to connect psql to an AlloyDB instance involves these tasks:

  1. Create a Compute Engine VM that can connect to AlloyDB instances using private services access.
  2. Install the psql client on the Compute Engine VM.
  3. Get the IP address of the AlloyDB instance you want to connect to.
  4. Run the psql client.

The first two of these tasks are one-time operations. After you create a Compute Engine VM and install the psql client on it, you can continue to use the VM to connect psql to AlloyDB instances by performing remaining tasks.

Before you begin

  • The Google Cloud project you are using must have been enabled to access AlloyDB.
  • A VPC network in the Google Cloud project that you are using must already be configured for private services access to AlloyDB.
  • You must have one of these IAM roles in the Google Cloud project you are using:
    • roles/alloydb.admin (the AlloyDB Admin predefined IAM role)
    • roles/owner (the Owner basic IAM role)
    • roles/editor (the Editor basic IAM role)

    If you don't have any of these roles, contact your Organization Administrator to request access.

  • If the client host has a firewall, it must allow egress connections to port 5432 on your AlloyDB instances' IP addresses.

Create a Compute Engine VM

  1. In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  2. Select the project containing the AlloyDB instance you want to connect to.
  3. Click Create instance.
  4. Click the Machine configuration section.
  5. Enter a Name for the instance.
  6. Configure the region and zone where you want to create the instance.
  7. Select a machine series and the corresponding machine type.
  8. Retain the default values in the OS and Storage section.
  9. Click the Networking section, and set Network interfaces to the VPC network configured for private services access to AlloyDB.
    If Network interfaces is not set to the VPC network configured for private services access, expand it and then set Network to the VPC network.
  10. Retain the default values in the Observability section.
  11. Click the Security section.
  12. In Identity and API access, set Access scopes to Allow full access to all Cloud APIs.
  13. Retain the default values in the Advanced section.
  14. Click Create.

After the VM is created, connect to the Compute Engine VM you created using SSH.

Install the psql client tool

  1. Connect to the Compute Engine VM you created using SSH.

    Console

    1. In the Google Cloud console, go to the VM instances page.

      Go to VM instances

    2. In the list of virtual machine instances, click SSH in the row of the instance you created.

    gcloud

    Use the gcloud compute ssh command to connect to the instance you created.

    gcloud compute ssh --project=PROJECT_ID --zone=ZONE VM_NAME

    Replace the following:

    • PROJECT_ID: the ID of the project that contains the instance
    • ZONE: the name of the zone in which the instance is located
    • VM_NAME: the name of the instance
  2. Install the psql client from the package manager: 
    sudo apt-get update
sudo apt-get install postgresql-client

Get the IP address of the AlloyDB instance

To get the IP address of the AlloyDB instance you want to connect to, view that instance's settings.

Run the psql client

  1. Connect to the VM you created using SSH.

    Console

    1. In the Google Cloud console, go to the VM instances page.

      Go to VM instances

    2. In the list of virtual machine instances, click SSH in the row of the instance you created.

    gcloud

    Use the gcloud compute ssh command to connect to the instance you created.

    gcloud compute ssh --project=PROJECT_ID --zone=ZONE VM_NAME

    Replace the following:

    • PROJECT_ID: the ID of the project that contains the instance.
    • ZONE: the name of the zone in which the instance is located.
    • VM_NAME: the name of the instance.
  2. Run the psql client tool: 
    psql -h IP_ADDRESS -U USERNAME -d postgres

    You are prompted to enter the password of the USERNAME user.

    If you're connecting for the first time, specify postgres for both the USERNAME and the database. Your command looks like the following:

    psql -h IP_ADDRESS -U postgres -d postgres

    Use the password that you set when you created the cluster.