Stay organized with collections
Save and categorize content based on your preferences.
This page describes how to connect the psql client tool to
an AlloyDB instance.
The procedure to connect psql to an AlloyDB
instance involves these tasks:
Create a Compute Engine VM that can connect to AlloyDB
instances using private services access.
Install the psql client on the Compute Engine VM.
Get the IP address of the AlloyDB instance you want to connect
to.
Run the psql client.
The first two of these tasks are one-time operations. After you create a
Compute Engine VM and install the psql client on it, you can continue
to use the VM to connect psql to AlloyDB instances by
performing remaining tasks.
Select the project containing the AlloyDB instance you
want to connect to.
Click Create instance.
Click the Machine configuration section.
Enter a Name for the instance.
Configure the region and zone where you want to create the instance.
Select a machine series and the corresponding machine type.
Retain the default values in the OS and Storage section.
Click the Networking section, and set Network interfaces to the VPC network configured for private services access to AlloyDB.
If Network interfaces is not set to the VPC network
configured for private services access, expand it and then set
Network to the VPC network.
Retain the default values in the Observability section.
Click the Security section.
In Identity and API access, set Access scopes to Allow full access to all Cloud APIs.
Retain the default values in the Advanced section.
Click Create.
After the VM is created, connect to the Compute Engine VM you created using SSH.
Install the psql client tool
Connect to the Compute Engine VM you created using SSH.
Console
In the Google Cloud console, go to the VM instances
page.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-26 UTC."],[[["\u003cp\u003eThis page provides instructions on how to connect the \u003ccode\u003epsql\u003c/code\u003e client tool to an AlloyDB instance.\u003c/p\u003e\n"],["\u003cp\u003eConnecting \u003ccode\u003epsql\u003c/code\u003e to AlloyDB requires creating a Compute Engine VM, installing the \u003ccode\u003epsql\u003c/code\u003e client on it, and obtaining the AlloyDB instance's IP address.\u003c/p\u003e\n"],["\u003cp\u003eThe initial setup involves creating the Compute Engine VM and installing the \u003ccode\u003epsql\u003c/code\u003e client, which are one-time operations.\u003c/p\u003e\n"],["\u003cp\u003eBefore connecting, ensure the project has AlloyDB access enabled, a VPC network configured for private services, and appropriate IAM roles, and that firewall rules allow egress connections to port 5432 on the AlloyDB instance's IP.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003epsql\u003c/code\u003e client is run by using the command \u003ccode\u003epsql -h IP_ADDRESS -U USERNAME\u003c/code\u003e after connecting to the VM via SSH, and you need to know the default \u003ccode\u003epostgres\u003c/code\u003e username and password.\u003c/p\u003e\n"]]],[],null,["# Connect a psql client to an instance\n\nThis page describes how to connect the `psql` client tool to\nan AlloyDB instance.\n\nThe procedure to connect `psql` to an AlloyDB\ninstance involves these tasks:\n\n1. Create a Compute Engine VM that can connect to AlloyDB instances using private services access.\n2. Install the `psql` client on the Compute Engine VM.\n3. Get the IP address of the AlloyDB instance you want to connect to.\n4. Run the `psql` client.\n\nThe first two of these tasks are one-time operations. After you create a\nCompute Engine VM and install the `psql` client on it, you can continue\nto use the VM to connect `psql` to AlloyDB instances by\nperforming remaining tasks.\n\n\nBefore you begin\n----------------\n\n- The Google Cloud project you are using must have been [enabled to access AlloyDB](/alloydb/docs/project-enable-access).\n- A VPC network in the Google Cloud project that you are using must already be [configured for private\n services access](/alloydb/docs/configure-connectivity) to AlloyDB.\n- You must have one of these IAM roles in the Google Cloud project you are using:\n - `roles/alloydb.admin` (the AlloyDB Admin predefined IAM role)\n - `roles/owner` (the Owner basic IAM role)\n - `roles/editor` (the Editor basic IAM role)\n\n If you don't have any of these roles, contact your Organization Administrator to request\n access.\n- If the client host has a firewall, it must allow egress connections to port 5432 on your AlloyDB instances' IP addresses.\n\n\u003cbr /\u003e\n\nCreate a Compute Engine VM\n--------------------------\n\n1. In the Google Cloud console, go to the **VM instances** page.\n\n [Go to VM instances](https://console.cloud.google.com/compute/instances)\n2. Select the project containing the AlloyDB instance you want to connect to.\n3. Click **Create instance**.\n4. Click the **Machine configuration** section.\n5. Enter a **Name** for the instance.\n6. Configure the region and zone where you want to create the instance.\n7. Select a machine series and the corresponding machine type.\n8. Retain the default values in the **OS and Storage** section.\n9. Click the **Networking** section, and set **Network interfaces** to the VPC network configured for private services access to AlloyDB. \n If **Network interfaces** is not set to the VPC network configured for private services access, expand it and then set **Network** to the VPC network.\n10. Retain the default values in the **Observability** section.\n11. Click the **Security** section.\n12. In **Identity and API access** , set **Access scopes** to **Allow full access to all Cloud APIs**.\n13. Retain the default values in the **Advanced** section.\n14. Click **Create**.\n\nAfter the VM is created, connect to the Compute Engine VM you created using SSH.\n\nInstall the psql client tool\n----------------------------\n\n1. Connect to the Compute Engine VM you created using SSH. By default, SSH connections to Compute Engine VMs use Identity-Aware Proxy. Depending on your organization's networking policies, you might need to [create an ingress firewall\n rule](/iap/docs/using-tcp-forwarding#firewall) to allow traffic to your VMs. \n\n ### Console\n\n 1. In the Google Cloud console, go to the **VM instances** page.\n\n [Go to VM instances](https://console.cloud.google.com/compute/instances)\n 2. In the list of virtual machine instances, click **SSH** in the row of the instance you created.\n\n ### gcloud\n\n Use the [`gcloud compute\n ssh` command](/sdk/gcloud/reference/compute/ssh) to connect to the instance you created. \n\n ```\n gcloud compute ssh --project=PROJECT_ID --zone=ZONE VM_NAME\n ```\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the ID of the project that contains the instance\n - \u003cvar translate=\"no\"\u003eZONE\u003c/var\u003e: the name of the zone in which the instance is located\n - \u003cvar translate=\"no\"\u003eVM_NAME\u003c/var\u003e: the name of the instance\n2. Install the psql client from the package manager: \n\n ```\n sudo apt-get update\n sudo apt-get install postgresql-client\n ```\n\nGet the IP address of the AlloyDB instance\n------------------------------------------\n\nTo get the IP address of the AlloyDB instance you want to connect\nto, [view that instance's settings](/alloydb/docs/instance-view).\n\nRun the psql client\n-------------------\n\n1. Connect to the VM you created using SSH. \n\n ### Console\n\n 1. In the Google Cloud console, go to the **VM instances** page.\n\n [Go to VM instances](https://console.cloud.google.com/compute/instances)\n 2. In the list of virtual machine instances, click **SSH** in the row of the instance you created.\n\n ### gcloud\n\n Use the [`gcloud compute\n ssh` command](/sdk/gcloud/reference/compute/ssh) to connect to the instance you created. \n\n ```\n gcloud compute ssh --project=PROJECT_ID --zone=ZONE VM_NAME\n ```\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the ID of the project that contains the instance.\n - \u003cvar translate=\"no\"\u003eZONE\u003c/var\u003e: the name of the zone in which the instance is located.\n - \u003cvar translate=\"no\"\u003eVM_NAME\u003c/var\u003e: the name of the instance.\n2. Run the `psql` client tool: \n\n ```\n psql -h IP_ADDRESS -U USERNAME -d postgres\n ```\n\n You are prompted to enter the password of the \u003cvar translate=\"no\"\u003eUSERNAME\u003c/var\u003e user.\n\n If you're connecting for the first time, specify `postgres` for both the \u003cvar translate=\"no\"\u003eUSERNAME\u003c/var\u003e and the database. Your command looks like the following: \n\n ```\n psql -h IP_ADDRESS -U postgres -d postgres\n ```\n\n Use the password that you set when you created the cluster."]]
