21.6.3 Adding Instances to a Replica Set

For an instance to be able to join a replica set, the following prerequisites must be satisfied. They are automatically checked by ReplicaSet.addInstance(), and the operation fails if any issues are found.

If the selected recovery method is incremental:

If MySQL Clone is available on both the primary and the instance you want to add to the replica set, the prerequisites listed above can be overcome by using clone as the recovery method.

Once you have created a replica set and assigned it to a variable, use the ReplicaSet.addInstance(instance) operation to add secondary instances to the replica set. You specify the instance as a URI-like connection string, see Section 4.2.5, “Connecting to the Server Using URI-Like Strings or Key-Value Pairs”. The user you specify must have the privileges required and must be the same on all instances in the replica set, see Configuring InnoDB Replica Set Instances. If you want to check the operation but not actually make any changes, use the dryRun option. This shows what actions the MySQL Shell would take to add the instance to the replica set.

For example to add the instance at rs-2 with user rsadmin, issue:

mysql-js> rs.addInstance('rsadmin@rs-2')

Adding instance to the replicaset...

* Performing validation checks

This instance reports its own address as rsadmin@rs-2
rsadmin@rs-2: Instance configuration is suitable.

* Checking async replication topology...

* Checking transaction state of the instance...

NOTE: The target instance 'rsadmin@rs-2' has not been pre-provisioned (GTID set
is empty). The Shell is unable to decide whether replication can completely
recover its state.  The safest and most convenient way to provision a new
instance is through automatic clone provisioning, which will completely
overwrite the state of 'rsadmin@rs-2' with a physical snapshot from an existing
replicaset member. To use this method by default, set the 'recoveryMethod'
option to 'clone'.

WARNING: It should be safe to rely on replication to incrementally recover the
state of the new instance if you are sure all updates ever executed in the
replicaset were done with GTIDs enabled, there are no purged transactions and
the new instance contains the same GTID set as the replicaset or a subset of it.
To use this method by default, set the 'recoveryMethod' option to 'incremental'.
Please select a recovery method [C]lone/[I]ncremental recovery/[A]bort (default Clone):

In this case we did not specify the recovery method, so the operation advises you on how to best proceed. In this example we choose the clone option because we do not have any existing transactions on the instance joining the replica set. Therefore there is no risk of deleting data from the joining instance.

Please select a recovery method [C]lone/[I]ncremental recovery/[A]bort (default Clone): C
* Updating topology
Waiting for clone process of the new member to complete. Press ^C to abort the operation.
* Waiting for clone to finish...
NOTE: rsadmin@rs-2 is being cloned from rsadmin@rs-1
** Stage DROP DATA: Completed
** Clone Transfer  
FILE COPY  ############################################################  100%  Completed
PAGE COPY  ############################################################  100%  Completed
REDO COPY  ############################################################  100%  Completed
** Stage RECOVERY: \
NOTE: rsadmin@rs-2 is shutting down...

* Waiting for server restart... ready
* rsadmin@rs-2 has restarted, waiting for clone to finish...
* Clone process has finished: 59.63 MB transferred in about 1 second (~1.00 B/s)

** Configuring rsadmin@rs-2 to replicate from rsadmin@rs-1
** Waiting for new instance to synchronize with PRIMARY...

The instance 'rsadmin@rs-2' was added to the replicaset and is replicating from rsadmin@rs-1.

Assuming the instance is valid for InnoDB ReplicaSet usage, distributed recovery proceeds. In this case the newly joining instance uses MySQL Clone to copy all of the transactions it has not yet applied from the primary, then it joins the replica set as an online instance. To verify, use the ReplicaSet.status() operation:

mysql-js> rs.status()
{    
    "replicaSet": {
        "name": "example", 
        "primary": "rs-1:3306", 
        "status": "AVAILABLE", 
        "statusText": "All instances available.", 
        "topology": {
            "rs-1:3306": {
                "address": "rs-1:3306", 
                "instanceRole": "PRIMARY", 
                "mode": "R/W", 
                "status": "ONLINE"
            }, 
            "rs-2:3306": {
                "address": "rs-2:3306", 
                "instanceRole": "SECONDARY", 
                "mode": "R/O", 
                "replication": {
                    "applierStatus": "APPLIED_ALL", 
                    "applierThreadState": "Slave has read all relay log; waiting for more updates", 
                    "receiverStatus": "ON", 
                    "receiverThreadState": "Waiting for master to send event", 
                    "replicationLag": null
                }, 
                "status": "ONLINE"
            }
        }, 
        "type": "ASYNC"
    }
}

This output shows that the replica set named example now consists of two MySQL instances, and that the primary is rs-1. Currently there is one secondary instance at rs-2, which is a replica of the primary. The replica set is online, which means that the primary and secondary are in synchrony. At this point the replica set is ready to process transactions.

If you want to override the interactive MySQL Shell mode trying to choose the most suitable recovery method, use the recoveryMethod option to configure how the instance recovers the data required to be able to join the replica set. For more information, see Section 21.2.5, “Using MySQL Clone with InnoDB cluster”.