MySQL Shell 8.0 (part of MySQL 8.0)

6.3.3 Adding Instances to a ReplicaSet

When you have created a ReplicaSet you can use the ReplicaSet.addInstance() operation to add an instance as a read-only secondary replica of the current primary of the ReplicaSet. The primary of the ReplicaSet must be reachable and available during this operation. MySQL Replication is configured between the added instance and the primary, using an automatically created MySQL account with a random password. Before the instance can be an operational secondary, it must be in synchrony with the primary. This process is called recovery, and InnoDB ReplicaSet supports different methods which you configure with the recoveryMethod option.

For an instance to be able to join a ReplicaSet, various prerequisites must be satisfied. They are automatically checked by ReplicaSet.addInstance(), and the operation fails if any issues are found. Use dba.configureReplicaSetInstance() to validate and configure binary log and replication related options before adding an instance. MySQL Shell connects to the target instance using the same user name and password used to obtain the ReplicaSet handle object. All instances of the ReplicaSet are expected to have the same administrator account with the same grants and passwords. A custom administrator account with the required grants can be created while an instance is configured with dba.configureReplicaSetInstance(). See Configuring InnoDB ReplicaSet Instances.

Recovery Methods for InnoDB ReplicaSet

When new instances are added to an InnoDB ReplicaSet they need to be provisioned with the existing data which it contains. This can be done automatically using one of the following methods:

  • MySQL Clone, which takes a snapshot from an online instance and then replaces any data on the new instance with the snapshot. MySQL Clone is well suited for joining a new blank instance to an InnoDB ReplicaSet. It does not rely on there being a complete binary log of all transactions applied by the InnoDB ReplicaSet.

    Warning

    All previous data on the instance being added is destroyed during a clone operation. All MySQL settings not stored in tables are however maintained.

  • incremental recovery, which relies on MySQL Replication to apply all missing transactions on the new instance. If the amount of transactions missing on the new instance is small, this can be the fastest method. However, this method is only usable if at least one online instance in the InnoDB ReplicaSet has a complete binary log, containing the entire transaction history of the InnoDB ReplicaSet. This method cannot be used if the binary logs have been purged from all members or if the binary log was only enabled after databases already existed in the instance. If there is a very large amount of transactions to apply, there could be a long delay before the instance can join the InnoDB ReplicaSet.

When an instance is joining a ReplicaSet, recovery is used in much the same way that it is in InnoDB Cluster. MySQL Shell attempts to automatically select a suitable recovery method. If it is not possible to choose a method safely, MySQL Shell prompts for what to use. For more information, see Section 6.2.2.2, “Using MySQL Clone with InnoDB Cluster”. This section covers the differences when adding instances to a ReplicaSet.

Adding Instances to a ReplicaSet

Use the ReplicaSet.addInstance(instance) operation to add secondary instances to the ReplicaSet. You specify the instance as a URI-like connection string. The user you specify must have the privileges required and must be the same on all instances in the ReplicaSet, see Configuring InnoDB ReplicaSet Instances.

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 ReplicaSet. 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, 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 ReplicaSet 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": "Replica has read all relay log; waiting for more updates",
                    "receiverStatus": "ON",
                    "receiverThreadState": "Waiting for source to send event",
                    "replicationLag": null
                },
                "status": "ONLINE"
            }
        },
        "type": "ASYNC"
    }
}

This output shows that the ReplicaSet 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 ReplicaSet is online, which means that the primary and secondary are in synchrony. At this point the ReplicaSet 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 ReplicaSet. For more information, see Section 6.2.2.2, “Using MySQL Clone with InnoDB Cluster”.

MySQL Documentation Library