21.6.2 Deploying InnoDB ReplicaSet

To use InnoDB ReplicaSet you should be aware of the following prerequisites:

AdminAPI and InnoDB ReplicaSet enable you to work with MySQL replication without a deep understanding of the underlying concepts. However, for background information see Chapter 17, Replication.

Use dba.configureReplicaSetInstance(instance) to configure each instance you want to use in your replica set. MySQL Shell can either connect to an instance and then configure it, or you can pass in instance to configure a specific remote instance. How you proceed depends on whether the instance supports persisting settings, see Persisting Settings. For example, on an instance which does not support persisting settings, connect with a user with suitable privileges to configure the instance:

mysql-js> \connect root@example1.com:3306

The dba.configureReplicaSetInstance() function can optionally create an administrator account, if the clusterAdmin option is provided. The account is created with the correct set of privileges required to manage InnoDB cluster and InnoDB ReplicaSet. The preferred method to create users to administer a replica set is using the clusterAdmin option.

To configure the instance at rs-1:3306, with a cluster administrator named rsadmin issue:

mysql-js> dba.configureReplicaSetInstance('root@rs-1:3306', \ 
{clusterAdmin: "'rsadmin'@'rs-1%'"});

The interactive prompt requests the password required by the specified user. To configure the instance MySQL Shell is currently connected to, you can specify a null instance definition. For example issue:

mysql-js> dba.configureReplicaSetInstance('', {clusterAdmin: "'rsadmin'@'rs-1%'"});

The interactive prompt requests the password required by the specified user. This checks the instance which MySQL Shell is currently connected to is valid for use in a InnoDB ReplicaSet. Settings which are not compatible with InnoDB ReplicaSet are configured if possible. The cluster administrator account is created with the privileges required for InnoDB ReplicaSet.

Once you have configured your instances, connect to an instance and use dba.createReplicaSet() to create a managed replica set that uses MySQL asynchronous replication, as opposed to MySQL Group Replication used by InnoDB cluster. The MySQL instance which MySQL Shell is currently connected to is used as the initial primary of the replica set. Only TCP/IP connections are supported for this operation.

The dba.createReplicaSet() operation performs several checks to ensure that the instance state and configuration are compatible with a managed replica set and if so, a metadata schema is initialized on the instance. If you want to check the operation but not actually make any changes to the instances, use the dryRun option. This shows what actions the MySQL Shell would take to create the replica set. If the replica set is created successfully, a ReplicaSet object is returned. Therefore it is best practice to assign the returned ReplicaSet to a variable. This enables you to work with the replica set, for example by calling the ReplicaSet.status() operation. To create a replica set named example on instance rs-1 and assign it to the rs variable, issue:

mysql-js> \connect root@rs-1:3306
...
mysql-js> var rs = dba.createReplicaSet("example")
A new replicaset with instance 'rs-1:3306' will be created.

* Checking MySQL instance at rs-1:3306

This instance reports its own address as rs-1:3306
rs-1:3306: Instance configuration is suitable.

* Updating metadata...

ReplicaSet object successfully created for rs-1:3306.
Use rs.add_instance() to add more asynchronously replicated instances to this replicaset
and rs.status() to check its status.

To verify that the operation was successful, you work with the returned ReplicaSet object. For example this provides the ReplicaSet.status() operation, which displays information about the replica set. We already assigned the returned ReplicaSet to the variable rs, so issue:

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"
            }
        }, 
        "type": "ASYNC"
    }
}

This output shows that the replica set named example has been created, and that the primary is rs-1. Currently there is only one instance, and the next task is to add more instances to the replica set.