Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 47.5Mb
PDF (A4) - 47.6Mb
PDF (RPM) - 43.0Mb
HTML Download (TGZ) - 10.9Mb
HTML Download (Zip) - 11.0Mb
HTML Download (RPM) - 9.5Mb
Man Pages (TGZ) - 231.9Kb
Man Pages (Zip) - 337.3Kb
Info (Gzip) - 4.3Mb
Info (Zip) - 4.3Mb
Excerpts from this Manual

MySQL 8.0 Reference Manual  /  ...  /  Adding Instances to a Replica Set

21.6.3 Adding Instances to a Replica Set

When you have created a replica set you can use the ReplicaSet.addInstance() operation to add an instance as a read-only secondary replica of the current primary of the replica set. Therefore, the primary of the replica set 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. Once the instance is added to the replica set, the operation waits for the newly added instance to apply all pending transactions. This process is called distributed recovery, and MySQL Shell supports different methods which you configure with the recoveryMethod option.

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 replica set 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 Replica Set Instances.

When an instance is joining a replica set, distributed recovery is used in much the same way that it is in InnoDB cluster. This means that you can choose between MySQL Clone and incremental recovery. For more information, see Section 21.2.5, “Using MySQL Clone with InnoDB cluster”. This section covers the differences when using adding instances to a replica set.

Prerequisites

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.

  • binary log and replication related options must have been at least validated and also possibly configured by dba.configureReplicaSetInstance()

If the selected recovery method is incremental:

  • the transaction set on the instance being added must not contain transactions that do not exist on the primary

  • the transaction set on the instance being added must not be missing

  • transactions that have been purged from the binary log of the primary

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.

Adding Instances to a ReplicaSet

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”.