How to Add Read-Only Nodes

Validated on 8 Aug 2019 • Last edited on 7 Jun 2023 read-only node | standby node

PostgreSQL is an open source, object-relational database built with a focus on 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.

Read-only nodes are replicas of a cluster’s primary node located in additional geographical regions. Using read-only nodes reduces latency for users connecting from those regions.

Communication between primary and read-only nodes is SSL-encrypted and sent over the public network.

Note
Read-only nodes differ from standby nodes, which are exact copies of the primary node that are automatically moved into place in the event of a primary node failure.

Create a Read-Only Node Using the CLI

Note
To create a read-only node using doctl, you need to provide values --region and --size flags, which specify the node’s datacenter and its configuration (number of CPUs, amount of RAM, and hard disk space). Use the doctl databases options regions and doctl databases options slugs commands, respectively, to get a list of available values.
How to create a read-only node using the DigitalOcean CLI

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

                  doctl databases replica create <database-cluster-id> <replica-name> [flags]

    The following example creates a read-only replica named example-replica for a database cluster with the ID ca9f591d-f38h-5555-a0ef-1c02d1d1e35

                   doctl databases replica create ca9f591d-f38h-5555-a0ef-1c02d1d1e35 example-replica --size db-s-1vcpu-1gb

Create a Read-Only Node Using the API

Note
To create a read-only node using the API, you need to provide values for the region and size fields, which specify the new node’s 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 read-only node using the DigitalOcean API

To create a read-only node 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/{database_cluster_uuid}/replicas

    cURL

    To create a read-only node with cURL, call:

    
                curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"read-nyc3-01", "region":"nyc3", "size": "db-s-2vcpu-4gb", "storage_size_mib": 61440}' \
  "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas"

    Go

    Go developers can use Godo, the official DigitalOcean V2 API client for Go. To create a read-only node 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()

    replicaRequest := &godo.DatabaseCreateReplicaRequest{

        Name:   "read-nyc3-01",
        Region: "nyc3",
        Size:   "db-s-2vcpu-4gb",
        StorageSizeMiB : 61440,
    }

    replica, _, err := client.Databases.CreateReplica(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", replicaRequest)
}

    Python

    
                import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

create_req = {
  "name": "read-nyc3-01",
  "region": "nyc3",
  "size": "db-s-2vcpu-4gb",
  "storage_size_mib": 61440,
}

create_resp = client.databases.create_replica(database_cluster_uuid="9cc10173", body=create_req)

Create a Read-Only using the Control Panel

To add a read-only node, click on the name of the cluster to go to its Overview. At the bottom of the page, in the Read Only Nodes section, click the Add a read-only node link.

The read only nodes section of the overview page

Select the size, which must be equal to or larger than the primary node, then select the datacenter and name the node. When you’re done, click Create a read-only node to provision the node.

Like primary nodes, you can limit access to a read-only nodes to trusted sources and access read-only nodes using a command-line client and the connection string in the node’s Overview page.

Promote a Read-Only Node to Become a Primary Node

You can promote an existing read-only node to become the primary node of a new database cluster, essentially creating a fork or replica of its former database cluster. However, these two clusters are independent and do not remain in sync, so any changes you make to one are not copied to the other.

You can also promote a read-only node to create a new database cluster in a different datacenter region. This option can help you maintain uptime if a cluster is experiencing issues in another region.

How to promote a read-only node using the DigitalOcean CLI

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

                  doctl databases replica promote <database-cluster-id> <replica-name> [flags]

    The following example promotes a read-only replica named example-replica for a database cluster with the ID ca9f591d-f38h-5555-a0ef-1c02d1d1e35

                   doctl databases replica promote ca9f591d-f38h-5555-a0ef-1c02d1d1e35 example-replica
How to promote a read-only node using the DigitalOcean API

To promote a read-only node using the DigitalOcean API, follow these steps:

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

  2. Send a PUT request to https://api.digitalocean.com/v2/databases/{database_cluster_uuid}/replicas/{replica_name}/promote

    cURL

    To promote a read-only node with cURL, call:

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

    Go

    Go developers can use Godo, the official DigitalOcean V2 API client for Go. To promote a read-only node 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()

    _, err := client.Databases.PromoteReplicaToPrimary(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "read-nyc3-01")
}

    Python

    
                import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

resp = client.databases.promote_replica(database_cluster_uuid="a7a8bas", replica_name="ba8ab22")
Control Panel Blog Pricing Careers Terms Privacy Status API Docs Tutorials Support