Configuring Read-only Replicas

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.

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.

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.

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"
}'

curl -X POST \
  https://resource-controller.cloud.ibm.com/v2/resource_instances \
  -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"
  }'

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.

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}.databases.cloud.ibm.com/v4/ibm/deployments/{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}.databases.cloud.ibm.com/v4/ibm/deployments/{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}.databases.cloud.ibm.com/v4/ibm/deployments/{id}/remotes/promotion \
  -H 'Authorization: Bearer <>'  \
 -H 'Content-Type: application/json' \
 -d '{"promotion": {"skip_initial_backup": true}}' \