Read replica Considerations

• A read replica can exist in the same region as your source database instance or in a different one, enabling your data to be replicated across regions.

• A read replica must be the same major version as its source database instance.

• Backups are disabled on read replicas. Backups are taken only on source database instances.

• Read replication is not supported into or out of EU Cloud-enabled regions (currently eu-de). It is supported within those regions.

• There is a limit of five read replicas per source instance.

• The read replica does not participate in elections for the source database instance and failover to the read replica is not automated. Promotion of the read replica to a full deployment is a manual, user-initiated task.

• The minimum size of a read replica is 2 GB RAM and 20 GB of disk. This is true even if your source database instance deployment is smaller.

• Read replicas do not auto-scale to match the source database instance. If the amount of data you store outgrows the disk that is allocated to your deployments, scale the disk on the read replicas and then the source database instance. Scaling the read replica first ensures that you do not run out of space on the read replicas. If you scaled the source database instance's disk for performance and not for space, it is not necessary to scale the read 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 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 source database instance.

• A read 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 replicas, be sure to have logic to retry failed queries, or load-balancing over multiple read replicas.

• Databases for MySQL read replicas in Madrid (eu-es): The deployment of read replicas in Madrid in the eu-es region is currently suspended. Updates on availability will be provided as soon as possible.

The Leader

On the Read Replicas tab of a Databases for MySQL deployment before any read 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 replica that is already attached to it, then the Replication pane has a list of replica deployments and a link to each one.

Provisioning a Read Replica

You can provision a read replica from the leader's Read Replicas tab by clicking Create Read Replica. The source instance is automatically filled in. The read 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 source database instance deployment.

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

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

The Read Replica

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

mysql> SHOW SLAVE STATUS \G

Resyncing a Read Replica

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

The amount of time it takes to resync a read replica varies, but the process can be very 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 Replica

A read 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 source database instance, the read replica can be promoted to a stand-alone cluster and start accepting writes from your application.

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

Upon promotion, the read replica terminates its connection to the source database instance and becomes a stand-alone Databases for MySQL 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 three data members. This increases the cost as it is billed at the same per member consumption rate, but the deployment has three members instead of one.

When you promote a read 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 replica is promoted to an independent deployment, it is not possible to revert it back to a read replica, or have it rejoin a source database instance.

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