Connect to AlloyDB from Cloud Shell using the Auth Proxy

Learn how to establish a secure connection to your AlloyDB for PostgreSQL instance from a Cloud Shell terminal using the AlloyDB Auth Proxy. This quickstart is well-suited for new users who want a simple, pre-configured environment to connect to their instance and test basic SQL queries.

Before you begin

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  2. Make sure that billing is enabled for your Google Cloud project. Verifying billing enables all necessary services.

  3. Make sure that you have an AlloyDB instance configured for public IP. Cloud Shell can't connect to a private IP address.

Required roles

To use the Auth Proxy, your user account must have the following Identity and Access Management (IAM) roles :

If you don't have the required roles, ask your administrator to grant the roles or follow these steps to grant them to your user account.

  1. In the Google Cloud console, go to the IAM page.

    Go to IAM

  2. Find your user account in the list of principals.

  3. Click Edit principal.

  4. Click Add another role.

  5. Search for and select the AlloyDB Client role.

  6. Click Apply.

  7. Click Add another role.

  8. Search for and select the Service Usage Consumer role.

  9. Click Apply.

  10. Click Save.

Connect to your AlloyDB instance

The Cloud Shell environment includes the Auth Proxy (alloydb-auth-proxy) and psql, the PostgreSQL interactive terminal.

  1. Activate Cloud Shell.

    Activate Cloud Shell

  2. Click Authorize Cloud Shell. You only need to do this the first time you use Cloud Shell.

  3. Confirm your user identity in the Cloud Shell Editor. Verify that you're signed in with the user account that has the required IAM roles.

    gcloud config list

  4. Get the Connection URI for your instance.

    1. In the Google Cloud console, go to the Clusters page.

      Go to Clusters

    2. Select your cluster and find your primary instance.

    3. Click View connectivity configuration.

    4. Copy the Connection URI.

  5. Launch the Auth Proxy. In the Cloud Shell terminal, use the copied URI and specify the --public-ip flag.

    alloydb-auth-proxy CONNECTION_URI --public-ip

    Replace the following:

    • CONNECTION_URI: the Connection URI that you copied from the Google Cloud console.

    The Auth Proxy starts and displays a message confirming that it's listening on 127.0.0.1:5432.

  6. Open a new Cloud Shell tab, and connect to the database using psql.

    psql "host=localhost user=POSTGRES_USERNAME dbname=POSTGRES_DATABASE port=5432"

    To open a new terminal pane in the existing Cloud Shell window, press Control+b+"or click Add. This lets you keep the Auth Proxy running in one pane while you run connection commands in the second pane.

    To switch between panes, press Control+b+keyboard_arrow_up or Control+b+keyboard_arrow_down.

    Replace the following:

    • POSTGRES_USERNAME: your AlloyDB user, typically postgres.
    • POSTGRES_DATABASE: your AlloyDB database name, typically postgres.

  7. When prompted, enter the password for your PostgreSQL user.

  8. Verify the connection by running a SQL query.

    SELECT now();

  9. To stop psql, enter \q.

  10. To stop Cloud Shell, enter exit.

  11. To stop the Auth Proxy, enter Control+c.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

  1. In the Google Cloud console, go to the Clusters page.

    Go to Clusters

  2. Click the cluster that you created.

  3. Click Delete Cluster.

  4. In the confirmation dialog, enter the ID of the cluster and click Delete to delete the cluster and its instances.

What's next