--- title: How to Add Read-Only Nodes to PostgreSQL Database Clusters description: Add read-only nodes to reduce latency for users in specific regions. product: Databases url: https://docs.digitalocean.com/products/databases/postgresql/how-to/add-read-only-nodes/ last_updated: "2026-07-31" --- > **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document). # How to Add Read-Only Nodes 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. [Read-only nodes](https://docs.digitalocean.com/products/databases/index.html.md#cluster-configuration) 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](https://docs.digitalocean.com/products/databases/postgresql/how-to/add-standby-nodes/index.html.md), 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 Automation You can create a read-only node using the DigitalOcean CLI (`doctl`) or the API. ### Create a Read-Only Node via 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`](https://docs.digitalocean.com/reference/doctl/reference/databases/options/regions/index.html.md) and [`doctl databases options slugs`](https://docs.digitalocean.com/reference/doctl/reference/databases/options/slugs/index.html.md) commands, respectively, to get a list of available values. ## How to Create a Read-Only Node Using the DigitalOcean CLI 1. [Install `doctl`](https://docs.digitalocean.com/reference/doctl/how-to/install/index.html.md), the official DigitalOcean CLI. 2. [Create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) and save it for use with `doctl`. 3. Use the token to grant `doctl` access to your DigitalOcean account. ```shell doctl auth init ``` 4. Finally, run `doctl databases replica create`. Basic usage looks like this, but you can [read the usage docs](https://docs.digitalocean.com/reference/doctl/reference/databases/replica/create/index.html.md) for more details: ```shell doctl databases replica create [flags] ``` The following example creates a read-only replica named `example-replica` for a database cluster with the ID `ca9f591d-f38h-5555-a0ef-1c02d1d1e35`: ```shell doctl databases replica create ca9f591d-f38h-5555-a0ef-1c02d1d1e35 example-replica --size db-s-1vcpu-1gb ``` ### Create a Read-Only Node via 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`](https://docs.digitalocean.com/reference/api/reference/databases/index.html.md#databases_list_options) endpoint to get a list of available values. ## How to Create a Read-Only Node Using the DigitalOcean API [Create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) and save it for use with the API. ### cURL Send a POST request to [`https://api.digitalocean.com/v2/databases/{database_cluster_uuid}/replicas`](https://docs.digitalocean.com/reference/api/reference/databases/index.html.md#databases_create_replica). Using cURL: ```shell 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, "do_settings": {"service_cnames": ["replica-db.example.com", "read-replica.myapp.io"]}}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas" ``` ### Go Using [Godo](https://github.com/digitalocean/godo), the official DigitalOcean API client for Go: ```go 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, DOSettings: &godo.DOSettings{ ServiceCnames: []string{"replica-db.example.com", "read-replica.myapp.io"}, }, } replica, _, err := client.Databases.CreateReplica(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", replicaRequest) } ``` ### Python Using [PyDo](https://github.com/digitalocean/pydo), the official DigitalOcean API client for Python: ```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, "do_settings": { "service_cnames": [ "replica-db.example.com", "read-replica.myapp.io" ] } } 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 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](https://docs.digitalocean.com/screenshots/databases/read-only-nodes.a000dedadde28e8a72029bed94174164449e3ab73469265900f474e4b6400b54.png) 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](https://docs.digitalocean.com/products/databases/postgresql/how-to/secure/index.html.md#firewalls) 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 1. [Install `doctl`](https://docs.digitalocean.com/reference/doctl/how-to/install/index.html.md), the official DigitalOcean CLI. 2. [Create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) and save it for use with `doctl`. 3. Use the token to grant `doctl` access to your DigitalOcean account. ```shell doctl auth init ``` 4. Finally, run `doctl databases replica promote`. Basic usage looks like this, but you can [read the usage docs](https://docs.digitalocean.com/reference/doctl/reference/databases/replica/promote/index.html.md) for more details: ```shell doctl databases replica promote [flags] ``` The following example promotes a read-only replica named `example-replica` for a database cluster with the ID `ca9f591d-f38h-5555-a0ef-1c02d1d1e35`: ```shell doctl databases replica promote ca9f591d-f38h-5555-a0ef-1c02d1d1e35 example-replica ``` ## How to Promote a Read-Only Node Using the DigitalOcean API [Create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) and save it for use with the API. ### cURL Send a PUT request to [`https://api.digitalocean.com/v2/databases/{database_cluster_uuid}/replicas/{replica_name}/promote`](https://docs.digitalocean.com/reference/api/reference/databases/index.html.md#databases_promote_replica). Using cURL: ```shell 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 Using [Godo](https://github.com/digitalocean/godo), the official DigitalOcean API client for Go: ```go 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 Using [PyDo](https://github.com/digitalocean/pydo), the official DigitalOcean API client for Python: ```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") ```