MySQL :: MySQL Shell 8.4 :: 7.11.3 Modifying or Removing Read Replicas

Removing Read Replicas

To remove a Read Replica from a Cluster, use Cluster.removeInstance(). This operation performs the following tasks:

Drops the replication user from the Cluster.
Removes the Read Replica from the Cluster metadata.
Stops the replication channel and the Read Replica's configuration reset to default values.

Note

If Cluster.removeInstance() is run on a Cluster member which is also the source for a Read Replica, the failover process is triggered and the Read Replica attempts to connect to another source. If there is no other source available, the replication channel is stopped. The removed Cluster member is also removed from the Read Replica's source list.

The following example removes the Read Replica, host4:4110 from the Cluster:

Cluster.removeInstance("host4:4110")
Removing Read-Replica 'ipaddress:4110' from the Cluster 'myCluster'.

* Waiting for the Read-Replica to synchronize with the Cluster...
** Transactions replicated  ############################################################  100%

* Stopping and deleting the Read-Replica managed replication channel...

Read-Replica 'ipaddress:4110' successfully removed from the Cluster 'myCluster'.

When a Read Replica is removed, the transactions are synchronized with the source. You can define a timeout, in seconds, for the transaction replication process. For example:

Cluster.removeInstance("host4:4110", {timeout:30})

This defines a 30 second timeout on the synchronization process. If the synchronization process does not complete in 30 seconds, the removeInstance operation is rolled back and the Read Replica is not removed from the Cluster.

The default timeout value is 0 (zero), or no timeout.

You can test this operation using the dryRun option. Including this option, set to true runs the command but makes no changes. This enables you to test your changes.

Rejoining Read Replica to a Cluster

To rejoin a Read Replica to a Cluster, use Cluster.rejoinInstance().

Cluster.rejoinInstance(instance [, options])

To rejoin a Read Replica to a Cluster, the instance must meet the following requirements:

The target instance must be a member of the Cluster.
The target instance must meet the prerequisites for a Read Replica. See Section 7.11.1, “Prerequisites”.
The target instance's GTID set must not be different from the Cluster's. This does not apply if recoveryMethod: clone.

Note

If all the configured sources for the Read Replica are unreachable, or no longer part of the Cluster, the rejoinInstance() operation will fail. In this scenario, you must update the Read Replica's replication sources using Cluster.setInstanceOption().

This process is identical to rejoining a Cluster member to a Cluster, with the following exceptions:

The recoveryMethod value clone and the option cloneDonor are only available for Read Replicas.
The timeout option is only available for Read Replicas.

The following example, shows an attempt to rejoin a Read Replica, host4:4110 to a Cluster using the default recovery method:

Cluster.rejoinInstance('host4:4110')

When a Read Replica is rejoined, the transactions are synchronized with the primary. You can define a timeout, in seconds, for the transaction replication process. The following example sets a 60 second timeout for the transaction synchronization process:

Cluster.rejoinInstance('host4:4110', {timeout: 60})

This defines a 60 second timeout on the synchronization process. If the synchronization process does not complete in 60 seconds, the rejoinInstance operation is rolled back and the Read Replica is not rejoined to the Cluster.

The default timeout value is 0 (zero), or no timeout.

You can test this operation using the dryRun option. Including this option, set to true runs the command but makes no changes. This enables you to test your changes.

Note

It is not possible to use rejoinInstance to rejoin a Read Replica which was removed from the Cluster using removeInstance. removeInstance removes the Read Replica from the Cluster and removes the Read Replica's metadata.

To rejoin such an instance, you must use addReplicaInstance.

Routing Read Replicas

The default routing policy for a Cluster is to direct all read-only traffic to the secondary members. Cluster.setRoutingOption() enables you to set the routing policy to one of the following values with the read_only_targets option:

all: all Read Replicas and Secondary Cluster members are used for read-only traffic.
read_replicas: only Read Replicas are used for read-only traffic.
secondaries: only Secondary Cluster members are used for read-only traffic.

The following example sets the read-only routing policy for a router named machine1::router1 to Read Replicas only:

Cluster.setRoutingOption("machine1::router1", "read_only_targets", "read_replicas")

To view the current routing policy of a router named machine1::router1, run the following:

Cluster.routingOptions("machine1::router1")