How to Create 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.


Create a Database Cluster Using the CLI

Note
To create a database using doctl, you need to provide values for the --engine, --region, and --size flags. Use the doctl databases options engines, doctl databases options regions, and doctl databases options slugs commands, respectively, to get a list of available values.
How to create a Database using the DigitalOcean CLI

To create a Database 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, create a Database with doctl databases create. The basic usage looks like this, but you'll want to read the usage docs for more details:

                  doctl databases create <name> [flags]
                

    The following example creates a database cluster named example-database in the nyc1 region with a single 1 GB node

                       doctl databases create example-database --region nyc1 --size db-s-1vcpu-1gb --num-nodes 1
                    

Create a Database Cluster Using the API

Note
To create a database using the API, you need to provide values for the engine, region, and size fields, which specify the database’s engine, its datacenter, and its configuration (number of CPUs, amount of RAM, and hard disk space). Use the /v2/databases/options endpoint to get a list of available values.
How to create a Database using the DigitalOcean API

To create a Database using the DigitalOcean API, follow these steps:

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

  2. Send a POST request to https://api.digitalocean.com/v2/databases

    cURL

    To create a Database with cURL, call:

    
                    curl -X POST \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
      -d '{"name": "backend", "engine": "pg", "version": "14", "region": "nyc3", "size": "db-s-2vcpu-4gb", "num_nodes": 2, "storage_size_mib": 61440, "tags": ["production"]}' \
      "https://api.digitalocean.com/v2/databases"

    Go

    Go developers can use Godo, the official DigitalOcean V2 API client for Go. To create a Database 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()
    
        createRequest := &godo.DatabaseCreateRequest{
            Name:       "backend",
            EngineSlug: "pg",
            Version:    "14",
            Region:     "nyc3",
            SizeSlug:   "db-s-2vcpu-4gb",
            NumNodes:   2,
            StorageSizeMiB : 61440,
        }
    
        cluster, _, err := client.Databases.Create(ctx, createRequest)
    }

    Python

    
                    import os
    from pydo import Client
    
    client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
    
    create_req = {
      "name": "backend",
      "engine": "pg",
      "version": "14",
      "region": "nyc3",
      "size": "db-s-2vcpu-4gb",
      "num_nodes": 2,
      "storage_size_mib": 61440,
      "tags": [
        "production"
      ]
    }
    
    create_resp = client.databases.create_cluster(body=create_req)

Create a Database Cluster Using the Control Panel

You can create a PostgreSQL database cluster at any time from the Create menu by selecting Databases. This takes you to the Create a Database page.

The Create menu

In the create menu, click Databases to open the database cluster creation page. This is where you choose your database cluster’s configuration, like the number and size of nodes and the datacenter region.

Choose a datacenter

In the Choose a datacenter section, select the datacenter for your database cluster.

The datacenter selection portion of the databases create page

This page lists the datacenters in which you currently have the most resources. The number of resources you have in each datacenter is listed to the right as X resources. Hover over this text to see the specific resources you have in that datacenter.

For the best performance, create your database in the same datacenter as your other DigitalOcean resources. After creation, you can relocate your cluster to another datacenter.

Note
Each region has one or more datacenters, each with a different VPC network. By including resources in the same datacenter, they all gain access to the same private networking interface, which reduces lag and keeps traffic between them from being routed over the public internet.

Choose a database engine

In the Choose a database engine section, choose PostgreSQL.

The database engine selection portion of the databases create page

We currently support major versions 12, 13, 14, 15, and 16 and the latest minor version is selected by default. You cannot change the PostgreSQL version after creating a cluster.

Choose a cluster configuration

In the Choose a cluster configuration section, select the machine type and the number and size of the database nodes. If you select the Shared CPU plan, you also need to select a CPU option. Each option lists its combined monthly cost, equivalent hourly cost, and node specifications. For more options, click See all plans.

The Choose a cluster configuration section of the Create a database page displaying the node size, standby nodes, and monthly cost

After creation, you can increase the number or size of database nodes at any time. However, because of data integrity risks, you cannot downsize nodes.

Choose a storage size

In the Choose a storage size section, you can increase your storage by clicking the up arrow or entering your desired storage amount, in increments of 10 GiB, up to the maximum listed in the storage range. Each 10 GiB of storage you add costs $2 per month.

You can increase your storage at any time. However, because of data integrity risks, you cannot reduce the amount of added storage in a cluster. If you need to downscale, you can instead fork the cluster and select a smaller storage size for the new cluster.

Finalize and Create

In the last section, Finalize and Create, choose the name for the cluster, the project to add it to, and any tags you want to use.

The Finalize and Create section of the Create a database page

There are three sub-headers in this section:

  • Choose a name: You can leave the automatically-generated name for the database or choose a custom name. Names must be unique, be between 3 and 63 characters long, and only contain alphanumeric characters, dashes, and periods.

  • Select a project: You can leave the default project or choose another one.

  • Tags: You can add a tag by typing it into the text box and pressing enter. Tags can only contain letters, numbers, colons, dashes, and underscores.

After creation, you can always edit the database’s tags or move it to another project; however, its name cannot be changed.

When you’re ready, click the Create a Database Cluster button.

Clusters typically take five minutes or more to provision, but you can complete important configuration tasks such as restricting inbound connections while you wait.