How to Connect to PostgreSQL Database Clusters

PostgreSQL is an open source, object-relational database built for extensibility, data integrity, and speed. Its concurrency support makes it fully ACID-compliant, and it supports dynamic loading and catalog-driven operations to let users customize its data types, functions, and more.


You can connect to DigitalOcean Managed Databases using command line tools and other third-party clients. This guide explains where to find your PostgreSQL database’s connection details and how to use them to configure tools and clients.

Retrieve Database Connection Details Using the CLI

How to retrieve database connection details using the DigitalOcean CLI

To retrieve database connection details via the command-line, follow these steps:

  1. Install doctl, the DigitalOcean command-line tool.

  2. Create a personal access token, and save it for use with doctl.

  3. Use the token to grant doctl access to your DigitalOcean account.

                  doctl auth init
                
  4. Finally, retrieve database connection details with doctl databases connection. The basic usage looks like this, but you'll want to read the usage docs for more details:

                  doctl databases connection <database-cluster-id> [flags]
                

    The following example retrieves the connection details for a database cluster with the ID f81d4fae-7dec-11d0-a765-00a0c91e6bf6

                       doctl databases connection f81d4fae-7dec-11d0-a765-00a0c91e6bf6
                    

Retrieve Database Connection Details Using the API

This API call retrieves the information about your database, including its connection details. The connection details are located in the returned connection JSON object.

How to retrieve database connection details using the DigitalOcean API

To retrieve database connection details using the DigitalOcean API, follow these steps:

  1. Create a personal access token, and save it for use with the API.

  2. Send a GET request to https://api.digitalocean.com/v2/databases/{database_cluster_uuid}

    cURL

    To retrieve database connection details with cURL, call:

    
                    curl -X GET \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
      "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30"

    Go

    Go developers can use Godo, the official DigitalOcean V2 API client for Go. To retrieve database connection details with Godo, use the following code:

    
                    import (
        "context"
        "os"
    
        "github.com/digitalocean/godo"
    )
    
    func main() {
        token := os.Getenv("DIGITALOCEAN_TOKEN")
    
        client := godo.NewFromToken(token)
        ctx := context.TODO()
    
        cluster, _, err := client.Databases.Get(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30")
    }

    Python

    
                    import os
    from pydo import Client
    
    client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
    
    get_resp = client.databases.get_cluster(database_cluster_uuid="a7a89a")

View PostgreSQL Cluster Connection Details

You use your database’s connection details to configure tools, applications, and resources that connect to the database. To view your database’s connection details, click the name of the cluster on the Databases page to go to its Overview page.

Databases Overview screen showing connection string

You can view customized connection details based on how you want to connect to the database:

  • Public network and Private network (VPC) options generate connection details based on if you want to connect via the cluster’s public hostname or the cluster’s private hostname. Only other resources in the same VPC network as the cluster can access it using its private hostname.

  • The Database/Pool field updates the connection details based on which database you want to connect to.

  • The User field updates the connection details with the user credentials that you would like to connect with.

You can also choose to view the connection details in three different formats:

  • Connection parameters: Database information meant for application configuration, such as configuring connections for DataGrip and pgAdmin.

  • Connection string: A condensed string that you can pass to a client on the command line.

  • Flags: A complete psql command that supplies the connection variables as individual flags.

We recommend the flags format because the readability can help if you want to customize the way you connect. The only required parameter is sslmode, but PostgreSQL supports many options for customizing connections.

By default, the control panel doesn’t reveal the cluster’s password for security reasons. Click Copy to copy connection details with the password, or click show-password to reveal the password.

Download the SSL Certificate

Each managed database comes with an SSL certificate. You can use this SSL certificate to encrypt connections between your client applications and the database.

To download your database’s SSL certificate, click the name of the cluster on the Databases page to go to its Overview page. In the Connection Details section, click Download CA certificate.

Databases connection details with Download CA Certificate selected

When you configure your client applications, you can use the certificate’s location on your local system. Each client application is configured differently, so check the documentation for the tool you’re using for more detail on setting up SSL connections.

Connect to the Database

You can connect and manage the database using a command line tool or an application that has a graphic user interface (GUI). In this guide, we show you how to connect to the database using the command line tool, psql, and the visual database management application, DataGrip.

To connect to PostgreSQL database clusters using psql, you need three things:

To connect using the flags format, paste the entire command from the control panel in your terminal:

PGPASSWORD=your_password psql -U doadmin -h cluster-do-user-1234567-0.db.ondigitalocean.com -p 25060 -d defaultdb --set=sslmode=require

To connect using the connection string, pass the string from the control panel in quotes to psql in your terminal:

psql "postgresql://your_username:your_password@cluster-do-user-1234567-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require"

When you connect successfully, your terminal changes to the psql prompt, which displays the name of the database you’re connected to, like defaultdb=>.

To connect using your database’s SSL certificate, update the flags commands with the sslrootcert variable and the path to the certificate on your local system:

PGPASSWORD=your_password psql -U doadmin -h cluster-do-user-1234567-0.db.ondigitalocean.com -p 25060 -d defaultdb --set=sslmode=require --set=sslrootcert=path/to/your-ssl.crt

From here, you can change databases or users, execute SQL queries, and perform other database administration tasks. Learn more about psql in our SQL cheat sheet and the official psql documentation.

If you’re having trouble connecting to the database, you can troubleshoot the connection using our Support page, or you can reference psql’s connection documentation.

To connect to PostgreSQL database clusters using DataGrip, you need three things:

To connect to your PostgreSQL database using a standard TCP/IP connection, open DataGrip, then click File, New Data Source, then select PostgreSQL from the list of options.

In the Data Sources and Drivers window, create a descriptive name for the connection in the Name field.

In the General tab, use the information from your database’s Connection Details section in the control panel to fill out the necessary fields.

DataGrip Data Sources and Drivers window with connection information

If you want to connect using SSL encryption, click the SSH/SSL tab. In the SSH/SSL tab, click the select the Use SSL option. In the CA File field, enter the path to your database’s SSL certificate on your local system. In the Mode field, select the Require option.

DataGrip Data Sources and Drivers SSL tab with connection information

Once you have entered the details, click Test Connection. If you receive the message with a green checkmark, click OK in the Data Sources and Drivers window to save the connection configuration. DataGrip automatically connects to the database. If you receive an error, recheck that you entered your credentials correctly and then reattempt the test.

If you’re having trouble connecting to the database, you can troubleshoot the connection using our Support page, or you can reference DataGrip’s connection documentation.