Connect from your laptop

This page describes how to establish a secure connection from your laptop or local machine to an AlloyDB for PostgreSQL instance using the AlloyDB Auth Proxy over a public IP address.

Connecting from your laptop is useful when you're exploring AlloyDB or you want to set up a development environment.

Before you begin

Before you connect from your laptop, make sure that you do the following:

Required roles

To connect from your laptop, make sure that your Identity and Access Management (IAM) principal (user account or service account) has the required 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