Connect to a cluster in Azure Cosmos DB for PostgreSQL

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

Choose one of the following database clients to see how to configure it to connect to an Azure Cosmos DB for PostgreSQL cluster.

pgAdmin

pgAdmin is a popular and feature-rich open source administration and development platform for PostgreSQL.

1. Download and install pgAdmin.

2. Open the pgAdmin application on your client computer. From the Dashboard, select Add New Server.

   

3. Choose a Name in the General tab. Any name will work.

   

4. Enter connection details in the Connection tab.

   

   Customize the following fields:

   • Host name/address: Obtain this value from the Overview page for your cluster in the Azure portal. It's listed there as Coordinator name. It will be of the form, c-<clustername>.12345678901234.postgres.cosmos.azure.com.
   • Maintenance database: use the value citus.
   • Username: use the value citus.
   • Password: the connection password or Microsoft Entra ID token. For more information, see authentication options.
   • Save password: enable if desired.

5. In the SSL tab, set SSL mode to Require.

   

6. Select Save to save and connect to the database.

psql

The psql utility is a terminal-based front-end to PostgreSQL. It enables you to type in queries interactively, issue them to PostgreSQL, and see the query results.

1. Install psql. It's included with a PostgreSQL installation, or available separately in package managers for several operating systems.

2. In the Azure portal, on the 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-<clustername>.<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-demo.12345678901234.postgres.cosmos.azure.com. This prefix indicates the coordinator node of the cluster. The default dbname and username are citus and can't be changed.

3. In the connection string you copied, replace <your_password> with your connection password or Microsoft Entra ID token. For more information, see authentication options.

4. In a local terminal prompt, paste the psql connection string, and then press Enter.

Next steps

• Troubleshoot connection issues.
• Verify TLS certificates in your connections.
• Now that you can connect to the database, learn how to build scalable apps.