MySQL Shell 8.4  /  ...  /  Rejoining a Cluster to an InnoDB ClusterSet

8.9.5 Rejoining a Cluster to an InnoDB ClusterSet

If an InnoDB Cluster is part of an InnoDB ClusterSet deployment, MySQL Shell automatically restores it to its role in the topology immediately after a reboot, provided that it is functioning acceptably and has not been marked as invalidated. However, if a cluster has been marked as invalidated or its ClusterSet replication channel has stopped, you must use a clusterSet.rejoinCluster() operation to rejoin it to the InnoDB ClusterSet deployment.

The clusterSet.rejoinCluster() operation verifies that the target cluster meets these requirements:

  • The cluster has previously been a member of the ClusterSet.

  • The cluster has quorum (sufficient members are online to form a majority).

  • The cluster's primary server is reachable.

  • The cluster is not holding any metadata locks or InnoDB transaction locks.

  • The cluster's GTID set (gtid_executed) contains no extra transactions compared to the active members of the ClusterSet, with the exception of view change events. These Group Replication internal transactions are identified by the UUID specified by the group_replication_view_change_uuid system variable, and the cluster rejoin process can reconcile them.

If the cluster meets these requirements, the operation restarts the ClusterSet replication channel and removes the INVALIDATED status. If it does not, you will need to fix any issues that were identified and retry the command.

Follow this procedure to rejoin an InnoDB Cluster to the InnoDB ClusterSet:

  1. Using MySQL Shell, connect to any member server in the primary cluster or in one of the replica clusters, using an InnoDB Cluster administrator account (created with cluster.setupAdminAccount()). You may also use the InnoDB Cluster server configuration account, which also has the required permissions. When the connection is established, get the ClusterSet object using dba.getClusterSet() or cluster.getClusterSet() command. It is important to use an InnoDB Cluster administrator account or server configuration account so that the default user account stored in the ClusterSet object has the correct permissions. For example:

    mysql-js> \connect admin2@127.0.0.1:3310
    Creating a session to 'admin2@127.0.0.1:3310'
    Please provide the password for 'admin2@127.0.0.1:3310': ********
    Save password for 'admin2@127.0.0.1:3310'? [Y]es/[N]o/Ne[v]er (default No):
    Fetching schema names for autocompletion... Press ^C to stop.
    Closing old connection...
    Your MySQL connection id is 28
    Server version: 8.0.27-commercial MySQL Enterprise Server - Commercial
    No default schema selected; type \use <schema> to set one.
    <ClassicSession:admin2@127.0.0.1:3310>
    mysql-js> myclusterset = dba.getClusterSet()
    <ClusterSet:testclusterset>
  2. Check the status of the whole deployment using AdminAPI's clusterSet.status() function in MySQL Shell. For example:

    mysql-js> myclusterset.status({extended: 1})

    For an explanation of the output, see Section 8.6, “InnoDB ClusterSet Status and Topology”.

  3. Issue a clusterSet.rejoinCluster() command, naming the cluster that you want to rejoin to the InnoDB ClusterSet. For example:

    mysql-js> myclusterset.rejoinCluster('clustertwo')
    Rejoining cluster 'clustertwo' to the clusterset
    NOTE: Cluster 'clustertwo' is invalidated
    * Updating metadata
    
    * Rejoining cluster
    ** Changing replication source of 127.0.0.1:4420 to 127.0.0.1:3310
    ** Changing replication source of 127.0.0.1:4430 to 127.0.0.1:3310
    ** Changing replication source of 127.0.0.1:4410 to 127.0.0.1:3310
    
    Cluster 'clustertwo' was rejoined to the clusterset

    For the clusterSet.rejoinCluster() command:

    • The clusterName parameter is required and specifies the identifier used for the cluster in the InnoDB ClusterSet, as given in the output from the clusterSet.status() command. In the example, clustertwo is the name of the cluster that is being rejoined.

    • Use the dryRun option if you want to carry out validations and log the changes without actually executing them.

    When you issue the clusterSet.rejoinCluster() command, MySQL Shell checks that the target cluster meets the requirements to rejoin the ClusterSet, and returns an error if it does not. If the target cluster meets the requirements, MySQL Shell carries out the following tasks:

    • Checks whether the ClusterSet replication channel is replicating from the current primary cluster, and reconfigures it to do that if it isn't already.

    • Restarts the ClusterSet replication channel.

    • Clears the INVALIDATED status for the cluster.

    The target cluster rejoins the InnoDB ClusterSet as a replica cluster, even if it was previously a primary cluster. A controlled switchover is required if you want to make the target cluster into the primary cluster.

    Note that if the target cluster has members that are not online or not reachable when you issue the clusterSet.rejoinCluster() command, these members are not correctly configured by the command. If you no longer require these instances, you can remove them using the cluster.removeInstance() command. If you repair these instances or bring them online again, issue the clusterSet.rejoinCluster() command again after those members return to the cluster.

  4. Issue a clusterSet.status() command again using the extended option, to verify the status of the InnoDB ClusterSet deployment.

  5. If you do want to make the rejoined cluster into the primary cluster, issue a clusterSet.setPrimaryCluster() command, naming the rejoined cluster. Section 8.7, “InnoDB ClusterSet Controlled Switchover” has instructions for the procedure, including how to direct MySQL Router instances to send traffic to the new primary cluster.