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.

Prerequisites

  • The Cloud project you are using must have been enabled to access AlloyDB.
  • A VPC network in the Cloud project you are using must already be configured for private services access to AlloyDB.
  • You must have one of these IAM roles in the 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.

Create a Compute Engine VM

  1. In the 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. Enter a Name for the instance and set these fields to enable access to AlloyDB instances:
    • Access scopes (located under Identity and API access): set to Allow full access to all Cloud APIs.
    • Network interfaces: set to the VPC network configured for private services access to AlloyDB:
      1. Expand Networking, disks, security, management, sole-tenancy.
      2. Expand Networking.
      3. 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.
  5. Click Create and wait for the VM to finish being created.

Install the psql client tool

  1. SSH into the Compute Engine VM you created.

    Console

    1. In the 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.

      SSH button next to instance name.

    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. SSH into the Compute Engine VM you created.

    Console

    1. In the 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.

      SSH button next to instance name.

    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

    You will be prompted to enter the password of the USERNAME user.

    If you're connecting for the first time, use the default value postgres for USERNAME and the password you used while creating the cluster for PASSWORD.