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.
   By default, SSH connections to Compute Engine VMs use Identity-Aware Proxy. Depending on your organization's networking policies, you might need to create an ingress firewall rule to allow traffic to your VMs.

   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

   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.