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:

Create a Compute Engine VM that can connect to AlloyDB instances using private services access.
Install the psql client on the Compute Engine VM.
Get the IP address of the AlloyDB instance you want to connect to.
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

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

Go to VM instances
Select the project containing the AlloyDB instance you want to connect to.
Click Create instance.
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 Advanced options.
  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.
Click Create and wait for the VM to finish being created.

Install the psql client tool

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

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

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