Introduction
For those who work with Google AlloyDB for PostgreSQL on a daily basis, connectivity is likely not an issue. As a developer or administrator, you probably already have a preferred set of tools and connection methods, or you use AlloyDB Studio to run quick queries.
However, when starting a new project or cluster — or if you are new to AlloyDB and looking for a straightforward way to connect via the command line with proper mTLS encryption — there is a new method available. You can now connect to an AlloyDB instance using the Google Cloud SDK (gcloud). Let me introduce you to how it works.
Setting up
The gcloud CLI is available out of the box on Google Cloud Shell and on Google Cloud Compute Engine VMs created with Google-provided templates. But, if you are running it from your laptop or a custom VM, you may need to install it by following the official documentation.
You also need two additional components to get everything working: a PostgreSQL client and the AlloyDB Auth Proxy. If you are using Google Cloud Shell, both components come preinstalled. However, if you are using your own laptop or VM, you will need to add them manually.
Let’s assume you’ve already installed the gcloud CLI. But before moving forward check the version using the versioncommand:
gcloud --version
It should return version 563 or higher.
my-mac:~ $ gcloud --version
Google Cloud SDK 564.0.0
...
If the version is lower then you need to update it:
gcloud components update
The next step is to get the PostgreSQL client software. The latest PostgreSQL client software can be downloaded from the official website, or installed via a package manager for Linux or the brew utility for macOS. Detailed instructions can be found in our documentation. Here is how to install version 18 using the Homebrew utility on a Mac:
brew install postgresql@18
After installing you can verify it by checking the version:
psql --version
The final component is the AlloyDB Auth Proxy. The gcloud CLI uses this proxy to create an mTLS-encrypted connection and establish a link to the instance. On a Mac, run the following commands:
URL="https://storage.googleapis.com/alloydb-auth-proxy/v1.14.2"
curl -o alloydb-auth-proxy "$URL/alloydb-auth-proxy.darwin.arm64"
chmod +x alloydb-auth-proxy
mkdir $HOME/bin
mv alloydb-auth-proxy $HOME/bin/
export PATH="$HOME/bin:$PATH"
See the AlloyDB Auth proxy documentation on how to install it for other platforms. By the way if your gcloud CLI cannot find the AlloyDB Auth Proxy in your system’s PATH, it will automatically provide instructions on how to install it.
Once all components are installed, you can run the gcloud beta alloydb instances connect command to access your database via the mTLS encryption provided by the proxy. Additionally, if you are connecting using an AlloyDB public IP, you do not need to add your personal public IP to the authorized networks; the proxy handles this automatically. Here is how I connect to my AlloyDB instance while testing a codelab:
REGION=us-central1
CLUSTER_NAME=alloydb-aip-01
INSTANCE_NAME=alloydb-aip-01-pr
gcloud beta alloydb connect $INSTANCE_NAME --cluster=$CLUSTER_NAME --region=$REGION --public-ip
Then you type your password for the user postgres and you are in.
my-mac:~ $ REGION=us-central1
my-mac:~ $ CLUSTER_NAME=alloydb-aip-01
my-mac:~ $ INSTANCE_NAME=alloydb-aip-01-pr
my-mac:~ $ gcloud beta alloydb connect $INSTANCE_NAME --cluster=$CLUSTER_NAME --region=$REGION --public-ip
Starting the AlloyDB Auth Proxy...
Running command:
alloydb-auth-proxy projects/gleb-genai-002/locations/us-central1/clusters/alloydb-aip-01/instances/alloydb-aip-01-pr --port 9471 --public-ip
Connecting to the AlloyDB Auth Proxy...
Running command:
psql -h 127.0.0.1 -p 9471 -U postgres -d postgres
Password for user postgres:
psql (18.0 (Postgres.app), server 16.11)
Type "help" for help.
postgres=>
A few final notes: You must be authenticated with an account that has the proper permissions to connect to AlloyDB instances, specifically the roles/alloydb.cloent and roless/serviceUsageConsumer roles. Additionally, if you want to use IAM authentication, ensure it is enabled on your AlloyDB cluster, that you have the roles/alloydb.databaseUser role, and that you have created the IAM user within the cluster itself.
As of the time of writing, this feature is still in Preview. And once more — you may need to update your Google Cloud SDK to version 563.0.0 or higher. For more details on available flags and configurations, refer to the official documentation regarding connecting via the gcloud CLI.
Happy testing! You can try it with some of our latest AlloyDB codelabs.
Top comments (0)