Connect to a cluster in Azure Cosmos DB for PostgreSQL

Important

Azure Cosmos DB for PostgreSQL is no longer supported for new projects. Don't use this service for new projects. Instead, use one of these two services:

• Use Azure Cosmos DB for NoSQL for a distributed database solution designed for high-scale scenarios with a 99.999% availability service level agreement (SLA), instant autoscale, and automatic failover across multiple regions.

• Use the Elastic Clusters feature of Azure Database For PostgreSQL for sharded PostgreSQL using the open-source Citus extension.

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.