Edit

Share via

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

  • Article

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 Cloud Shell to connect to an Azure Cosmos DB for PostgreSQL cluster.

Prerequisites

Connect

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

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

    Screenshot that shows copying the psql connection string.

    The psql string is of the form psql "host=c-<cluster>.<uniqueID>.postgres.cosmos.azure.com 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.com. 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.

  2. Open Azure Cloud Shell by selecting the Cloud Shell icon on the top menu bar.

    Screenshot that shows the Cloud Shell icon.

    If prompted, choose an Azure subscription in which to store Cloud Shell data.

  3. Paste your psql connection string into the shell.

  4. In the connection string, replace {your_password} with your cluster password or Microsoft Entra ID token, and then press Enter.

    Screenshot that shows running psql in the Cloud Shell.

    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=>

  5. 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)

Next steps

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

Create and distribute tables >