IBM Cloud Docs
Configuring Read-only Replicas

Configuring Read-only Replicas

You can set up your IBM Cloud® Databases for PostgreSQL deployment to be a read-only replica of another Databases for PostgreSQL deployment.

A read-only replica is set up to replicate all of your data from the leader deployment to the replica deployment through asynchronous replication. As the name implies, read-only replicas support read transactions and can be used to balance databases that have both write-heavy and read-heavy operations. The read-only replica has a single PostgreSQL data member, and it is billed at the same per member consumption rates as the leader.

Read-only Replica Considerations

  • The read-only replica can exist in the same region as the source formation or in different one, enabling your data to be replicated across regions.

  • A read-only replica must be the same major version as its leader.

  • Backups are disabled on read-only replicas. Backups are taken only on leader deployments.

  • Replicas are restorable to other regions, except for EU Cloud-enabled regions (currently eu-de and par-01), which are only restorable with each other (e.g., par-01 replicas can be restored to eu-de, and vice versa).

  • There is a limit of five read-only replicas per leader.

  • The read-only replica does not participate in leader->follower elections for the leader cluster and failover to the read-only replica is not automated. Promotion of the read-only replica to a full deployment is a manual, user-initiated task.

  • The minimum size of a read-only replica is 2 GB RAM and 10 GB of disk. This is true even if your leader deployment is smaller.

  • Read-only replicas do not auto-scale to match the leader. If the amount of data you store outgrows the disk that is allocated to your deployments, scale the disk on the read-only replicas and then the leader. Scaling the read-only replica first ensures that you do not run out of space on the read-only replicas. If you scaled the leader's disk for performance and not for space, it is not necessary to scale the read-only replicas.

  • Replication is asynchronous, and might be subject to replication lag. By default, there is no communication between the primary and replica regarding consistency. It is possible for a read-only replica to fall far enough behind that it needs to be resynced. Replication lag can be greater when the replica is in a region far away geographically from its leader.

  • A read-only replica is a deployment with single data member and does not have any internal high availability. It is prone to temporary interruptions and downtime during maintenance. If you have applications that rely on read-only replicas, be sure to have logic to retry failed queries, or load-balancing over multiple read-only replicas.

The Leader

On the Read Replicas tab of a Databases for PostgreSQL deployment before any read-only replicas are provisioned, the center pane notes that no read replicas exist and provides a Create button.

Replication pane before a replica
Figure 1. Replication pane before a replica

If a deployment is a leader and has a read-only replica that is already attached to it, then the Replication pane has a list of replica deployments and a link to each one. Click the cog to the right of the read-only replica's deployment name to manage it.

List of replicas that are attached to a leader
Figure 2. List of replicas that are attached to a leader

Provisioning a Read-only Replica

Resources for PostgreSQL deployments are allocated per-deployment, and normal deployments have two members. Since a read-only replica has only one member, and provisioning currently uses values that are half of the requested values for memory and storage, provisioning can fail. The web UI cannot modify the value for storage and it automatically uses the leader deployment’s value - which is cut in half. If that is insufficient for your data to fit, you need to use the API or CLI to specify twice the storage you want to be provisioned. (The same applies to memory, although a lower amount of memory might not prevent the restore from being successful.) An update is in progress to remediate this situation.

You can provision a read-only replica from the leader's Read Replicas tab by clicking Create Read-Only Replica. The source instance is automatically filled in. The read-only replica's name is auto-generated in the Service Name field, but you can rename it freely. You can choose the region to deploy it in, and its initial memory allocation. Disk size, version, and public or private endpoints are automatically configured to match the settings of the leader deployment.

If you use Key Protect, Bring Your Own Key (BYOK) is supported only when provisioning from the CLI and API. Otherwise, the read-only replica is encrypted with a generated key.

Provisioning through the API or the CLI

Provisioning a read-only replica through the CLI and the API works similarly to provisioning a standard Databases for PostgreSQL deployment. Provisioning is handled by the Resource Controller, and it uses a parameter {"remote_leader_id": "crn:v1:..."} to specify the leader of the replica you are provisioning.

For example, to provision a read-only replica through the CLI,

ibmcloud resource service-instance-create <replica_name> databases-for-postgresql standard <region> \
-p \ '{
  "remote_leader_id": "crn:v1:bluemix:public:databases-for-postgresql:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:1b8f53db-fc2d-4e24-8470-f82b15c71819::",
  "members_memory_allocation_mb": "2048",
  "members_disk_allocation_mb": "10240"

The same parameter is used to provision a read-only replica through the Resource Controller API.

curl -X POST \ \
  -H 'Authorization: Bearer <>' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "<replica_name>",
    "target": "<region>",
    "resource_group": "<your_resource_group_id>",
    "resource_plan_id": "databases-for-postgresql-standard",
    "remote_leader_id": "crn:v1:bluemix:public:databases-for-postgresql:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:1b8f53db-fc2d-4e24-8470-f82b15c71819::",
    "members_memory_allocation_mb": "2048",
    "members_disk_allocation_mb": "10240"

For both the CLI and API commands, you must specify both the RAM and disk amounts, keeping in mind the minimum size is 2 GB RAM and 10 GB disk. You can optionally specify whether the read-only replica uses public or private endpoints. You are not able to specify a version for the read-only replica. The version is automatically set to the same major version as the leader deployment.

The Read-only Replica

On the Read Replicas tab of a read-only replica, the Replication pane contains its name and region, and the name and region of its leader. It also has buttons to resync the read-only replica and to promote it.

Replication pane of a read-only replica
Figure 3. Replication pane of a read-only replica

Checking Replication Status

You must monitor replication as replication status is not automatically monitored.

You can check the replication status of a read-only replica with psql, but only from its leader. Connect to the leader deployment with psql using the admin credentials. Once you are connected run either,

  • For PostgreSQL version 10 and above SELECT * from pg_stat_replication;.


  • For PostgreSQL version 9.x and below SELECT * FROM get_pg_stat_replication();.

Read-only Replica Users and Privileges

  • Any user on the leader, even ones present before read-only replica provision, can log in to and run reads on a read-only replica with the same privileges to objects that they have on the leader.

  • If you have more than one read-only replica that is attached to a leader, a user that is created on the leader is also created on all of the other read-only replicas.

  • Users that are created on the leader persist on the read-only replica when it is promoted to a stand-alone deployment, including the admin user. When the read-only replica is promoted the users and privileges for all users on the leader are transferred to the promoted deployment.

  • Write operations on the read-only replica for all users are not filtered or rejected, but fail at the database level.

You can also create users with access to the read-only replica and no access to the leader from the read-only replica. If you have more than one read-only replica that is attached to a leader, a user that is created on any one of the read-only replicas is also created on all of the other read-only replicas.

Read-only replica users who are created on a read-only replica are able connect to the replicas and run reads. Read-only replica users are not able to connect and run operations on the leader. They also do not persist when a read-only replica is promoted to a stand-alone deployment.

Read-only replica created users are assigned privileges by the leader, and are assigned the ibm-cloud-base-user-ro role, and are members of the ibm-cloud-base-user group. They have access to all of the objects that are created by other members of this group, including any users on the leader that were created through Service Credentials, the CLI, or the API. Consistent with privileges of the ibm-cloud-base-user, a read-only replica-created user does not have access to objects created by the admin user, or other users created through psql. For more information, see the PostgreSQL Roles and Privileges page.

Resyncing a Read-only Replica

If you need to resync a read-only replica, click the Resync Read-Only Replica button. Resyncing is a disruptive operation and performing a resync tears down and rebuilds the data in the read-only replica. The read-only replica is not able to perform any other operations or run any queries while a resync is running. Queries are not rerouted to the leader, so any connections to the read-only replica fail until it is finished resyncing.

The amount of time it takes to resync a read-only replica varies, but the process can be long running.

To start a resync through the CLI, use the cdb read-replica-resync command.

ibmcloud cdb read-replica-resync <deployment name>

To start a resync through the API, send a POST to the /deployments/{id}/remotes/resync endpoint.

curl -X POST \
  https://api.{region}{id}/remotes/resync \
  -H 'Authorization: Bearer <>' 

Promoting a Read-only Replica

A read-only replica is able to be promoted to an independent cluster that can accept write operations as well as read operations. If something happens to the leader deployment, the read-only replica can be promoted to a stand-alone cluster and start accepting writes from your application.

To promote a read-only replica from the UI, click the Promote Read-Only Replica button.

Upon promotion, the read-only replica terminates its connection to the leader and becomes a stand-alone Databases for PostgreSQL deployment. The deployment can start accepting and running read and write operations, backups are enabled, and it is issued its own admin user. A new data member is added so the deployment becomes a cluster with two data members. This increases the cost as it is billed at the same per member consumption rate, but the deployment has two members instead of one.

When you promote a read-only replica, you can skip the initial backup that would normally be taken upon promotion. Skipping the initial backup means that your replica becomes available more quickly, but there is no immediate backup available. You can start an on-demand backup once the promotion process is complete.

Once a read-only replica is promoted to an independent deployment, it is not possible to revert it back to a read-only replica or have it rejoin a leader.

To promote through the CLI, use the cdb read-replica-promote command.

ibmcloud cdb read-replica-promote <deployment name>

To promote through the API, send a POST to the /deployments/{id}/remotes/promotion endpoint.

curl -X POST \
  https://api.{region}{id}/remotes/promotion \
  -H 'Authorization: Bearer <>'  \
 -H 'Content-Type: application/json' \
 -d '{"promotion": {}}' \ 

To promote and skip the initial backup after the promotion, also set skip_initial_backup in the JSON body.

curl -X POST \
  https://api.{region}{id}/remotes/promotion \
  -H 'Authorization: Bearer <>'  \
 -H 'Content-Type: application/json' \
 -d '{"promotion": {"skip_initial_backup": true}}' \ 

Time to completion

The promote task completes only when the database is highly available. However, read/write availability occurs after about 10 minutes with one major caveat: the database is not highly available until the task completes.

The full promotion time of a read-replica is determined by the size of the data in two possible ways:

  • Read replicas are single members. When promoted, the formation spec is changed to two members, which creates a second replica. The creation time of that replica depends on the size of the data. The creation of that replica runs at 25 MB/s to avoid saturating the network. As databases grow, the creation can take a substantial amount of time. The task does not complete until the creation of that replica is done.
  • If you choose to take a backup as part of the promotion, the completion of that backup also needs to finish before the task completes. Again, this depends on the size of the database.

Remember that there is no High-Availability member until the promotion task completes. Likewise, if you have selected to have an initial backup, no backup exists until the second point completes or a manual backup is created.

Upgrading while Promoting

If you need to upgrade to a new major version of the database, you can do so when promoting a read-only replica to a stand-alone deployment. Full documentation on your upgrading options, is on the Upgrading to a New Major Version page.