Connect using gcloud CLI

The gcloud beta alloydb connect command lets you establish an authorized, encrypted connection to an AlloyDB instance. It automates starting the AlloyDB Auth Proxy and running the psql client tool.

Use this command for manual database administration and development from environments like your local machine or Cloud Shell.

To learn more, see Connection overview.

Before you begin

  1. Install the gcloud CLI.
  2. Install the psql client tool.
  3. Ensure your IAM principal has the roles/alloydb.client role. For more information, see Manage IAM authentication.

Connect to an instance

To connect to an instance using the default postgres user and database over private IP, run:

gcloud beta alloydb connect INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID

Connect over public IP

If your instance has a public IP address enabled, you can connect to it by adding the --public-ip flag:

gcloud beta alloydb connect INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --public-ip

Authenticate using IAM

The gcloud beta alloydb connect command supports automatic IAM authentication. Use the --auto-iam-authn flag to authenticate as the logged-in gcloud user or a service account.

gcloud beta alloydb connect INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --auto-iam-authn

For more information about IAM authentication, see IAM database authentication.

Connect over Private Service Connect

If you are using Private Service Connect, add the --psc flag:

gcloud beta alloydb connect INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --psc

Connect with a specific user and database

To connect as a specific database user to a specific database, use the --user and --database flags:

gcloud beta alloydb connect INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --user=USER_NAME \
    --database=DATABASE_NAME

Service account impersonation

You can use an impersonated service account to authorize the connection. When you use impersonation, the AlloyDB Auth Proxy uses the credentials of the specified service account to retrieve connection information.

To connect using an impersonated service account, add the --impersonate-service-account flag:

gcloud beta alloydb connect INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

The Auth Proxy uses the impersonated service account to retrieve connection information. However, it does not automatically authenticate to the database. To also authenticate to the database as the impersonated service account, add the --auto-iam-authn flag. The impersonated service account must be a user in your database.

gcloud beta alloydb connect INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
    --auto-iam-authn

What's next