Connect to a cluster with psql - Azure Cosmos DB for PostgreSQL

APPLIES TO: Azure Cosmos DB for PostgreSQL (powered by the Citus database extension to PostgreSQL)

This quickstart shows you how to use the psql connection string in Azure CLI to connect to an Azure Cosmos DB for PostgreSQL cluster.

Prerequisites

An Azure account with an active subscription. If you don't have one, create a trial subscription.
An Azure Cosmos DB for PostgreSQL cluster. To create a cluster, see Create a cluster in the Azure portal.

Your cluster has a default database named citus. To connect to the database, you use a connection string and the admin password.

In the Azure portal, on your cluster page, select the Connection strings menu item, and then copy the psql connection string.

The psql string is of the form psql "host=c-<cluster>.<uniqueID>.postgres.cosmos.chinacloudapi.cn port=5432 dbname=citus user=citus password={your_password} sslmode=require". Notice that the host name starts with a c., for example c-mycluster.12345678901234.postgres.cosmos.azure.cn. This prefix indicates the coordinator node of the cluster. The default dbname is citus and can be changed only at cluster provisioning time. The user can be any valid Postgres role on your cluster.
Open your local CLI.
Paste your psql connection string into the CLI terminal.
In the connection string, replace {your_password} with your cluster password or Microsoft Entra ID token, and then press Enter.

When psql successfully connects to the database, you see a new citus=> (or the custom name of your database) prompt:
```
psql (14.2, server 14.5)
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off)
Type "help" for help.

citus=>
```
Run a test query. Paste the following command into the psql prompt, and then press Enter.
```
SHOW server_version;
```
You should see a result matching the PostgreSQL version you selected during cluster creation. For instance:
```
 server_version
----------------
 14.5
(1 row)
```

Now that you've connected to the cluster, the next step is to create tables and shard them for horizontal scaling.