Connect from your laptop

To explore AlloyDB for PostgreSQL or work in a local development environment, you can establish a secure connection from your laptop or local workstation to an AlloyDB instance by using the AlloyDB Auth Proxy over a public IP address.

Before you begin

Before you connect from your laptop, complete the following prerequisites:

Required roles

To connect from your laptop, grant your Identity and Access Management (IAM) principal (user account or service account) the following predefined roles:

  • AlloyDB Client (roles/alloydb.client)
  • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

Enable public IP on your AlloyDB instance

The most straightforward way to connect from your laptop is to enable public IP on your AlloyDB instance. You can enable public IP when you create an instance or you update an existing instance to enable it.

Console

  1. Go to the Clusters page in the Google Cloud console.

    Go to Clusters

  2. To view cluster details, click a cluster in the Resource Name.

  3. In Instances in your cluster, locate the instance you want to connect to.

  4. Click Instance actions and then click Edit.

  5. In Connectivity, select Enable Public IP.

  6. To save your changes, click Update instance.

gcloud

Use the gcloud alloydb instances update command to enable public IP on your instance:

gcloud alloydb instances update INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --assign-inbound-public-ip=ASSIGN_IPV4

Replace the following:

  • INSTANCE_ID: the ID of the AlloyDB instance.
  • CLUSTER_ID: the ID of the cluster.
  • REGION_ID: the region where the cluster is located.

Retrieve the instance connection URI

When you start the Auth Proxy client, you must identify your instance using its unique connection URI. Retrieve the connection URI using the gcloud CLI alloydb instances describe command on your laptop terminal.

gcloud alloydb instances describe INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --format="value(name)"

The command returns the connection URI, which is formatted similar to the following:

projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary

Start the AlloyDB Auth Proxy with public IP

Now that you have the instance connection URI, start the Auth Proxy client using your laptop terminal. Use the --public-ip flag to instruct the AlloyDB Auth Proxy to connect over the public IP network path.

./alloydb-auth-proxy CONNECTION_URI --public-ip

Replace CONNECTION_URI with the instance connection URI that you obtained in Retrieve the instance connection URI.

When the AlloyDB Auth Proxy starts successfully, the terminal shows that the AlloyDB Auth Proxy is listening for local TCP connections on port 5432:

Authorizing with Application Default Credentials
Listening on 127.0.0.1:5432
The proxy has started successfully and is ready for new connections!

Connect to the database using psql

While the AlloyDB Auth Proxy is running, open a separate terminal window on your laptop to connect to the database.

Run the psql client tool, targeting the local listener address 127.0.0.1 and port 5432:

psql -h 127.0.0.1 -U postgres -d postgres

When prompted, enter the password of the postgres database user.

The psql command connects to the Auth Proxy client, which forwards your connection through a secure tunnel to your AlloyDB instance. The psql command shows a prompt, confirming that your laptop is securely connected to the AlloyDB instance:

psql (18.2 (Debian 18.2-1), server 16.11)
Type "help" for help.

postgres=>

What's next