8.9.4 Removing a Cluster from an InnoDB ClusterSet

To remove a cluster from the InnoDB ClusterSet, use clusterSet.removeCluster() command. A force option is available if the cluster cannot be contacted at all.

clusterSet.removeCluster() has the following syntax:

         clusterSet.removeCluster(clusterName[, options])

Clusters can be removed from a ClusterSet by removing the Cluster, but leaving it intact, or by removing the Cluster and dissolving it into its member instances. All user data is retained by both methods.

A removed cluster is dissolved, by default, into its component instances. This is configured by the dissolve option, which defaults to true.

Important

The primary cluster in an InnoDB ClusterSet cannot be removed using this command. If you do need to remove the primary cluster, you must first carry out a controlled switchover (see Section 8.7, “InnoDB ClusterSet Controlled Switchover”) or an emergency failover (see Section 8.8, “InnoDB ClusterSet Emergency Failover”) to demote the primary cluster to a replica cluster, and promote one of the replica clusters to be the primary cluster. After that, the former primary cluster can be removed using this procedure.

A dissolved InnoDB Cluster cannot be added back into an InnoDB ClusterSet deployment. If you want to use the server instances in the deployment again, you can use them to set up a new cluster and add that cluster to the ClusterSet.

• Removing and Dissolving a Cluster

• Removing a Cluster and Updating as Standalone

Removing and Dissolving a Cluster

To remove a cluster from the InnoDB ClusterSet, and dissolve the cluster, follow this procedure:

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.

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

   When you issue the clusterSet.removeCluster() command, there must be an active and reachable primary cluster in the InnoDB ClusterSet deployment, and this must not be the cluster you are removing. The cluster you are removing must currently have the status of a replica cluster. It can be invalidated, and does not have to be reachable.

3. Check the routing options that are set for each MySQL Router instance, and the global policy for the InnoDB ClusterSet deployment, by issuing clusterSet.routingOptions() in MySQL Shell while connected to any member server in the InnoDB ClusterSet deployment. Verify that no MySQL Router instances are routing traffic to the cluster that you are going to remove. If any are, you must change their settings to route traffic to another cluster using a clusterSet.setRoutingOption() command, as described in Section 8.5, “Integrating MySQL Router With InnoDB ClusterSet”. A cluster cannot be removed if any MySQL Router instances known to the InnoDB ClusterSet deployment are routing traffic to it.

4. Issue a clusterSet.removeCluster() command, naming the cluster that you want to remove from the InnoDB ClusterSet. For example:

   mysql-js> myclusterset.removeCluster('clusterone')
   The Cluster 'clusterone' will be removed from the InnoDB ClusterSet.
   
   * Waiting for the Cluster to synchronize with the PRIMARY Cluster...
   ** Transactions replicated  ############################################################  100% 
   * Updating topology
   ** Transactions replicated  ############################################################  100% 
   * Stopping and deleting ClusterSet managed replication channel...
   
   The Cluster 'clusterone' was removed from the ClusterSet.

   • 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, clusterone is the cluster that is to be removed.

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

   • Use the timeout option to specify the maximum number of seconds to wait for the cluster to synchronize with the primary cluster in the InnoDB ClusterSet.

   • Use the force option to remove the cluster from the ClusterSet when the cluster's primary instance is not reachable.

   When you issue the clusterSet.removeCluster() command, MySQL Shell checks that the primary cluster in the InnoDB ClusterSet deployment is reachable, that the target cluster is not the primary cluster, and that no MySQL Router instances are routing traffic to the target cluster. If any of these conditions are not met, an error is returned. If they are met, MySQL Shell carries out the following tasks to remove the target cluster from the InnoDB ClusterSet:

   • Drops the replication user that was created for the ClusterSet replication channel on the target cluster.

   • Synchronizes the primary server of the target cluster with the primary cluster of the InnoDB ClusterSet, and waits for all transactions to be applied locally. If the timeout expires before this is completed, the operation fails. If synchronization does not work, try again with the force option.

   • Stops the ClusterSet replication channel, then removes the channel and resets its configuration to the default values.

   • Removes the target cluster's metadata and member information from the InnoDB ClusterSet metadata.

   • Leaves the super_read_only system variable set on all the member servers, to ensure that no updates are performed on them.

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

6. A removed InnoDB Cluster cannot be added back into an InnoDB ClusterSet deployment, so if you want to use the server instances in the deployment again, you will need to set up a new cluster using the standalone instances. The InnoDB Cluster is implicitly dissolved during the removal process, so that all the members become standalone instances.

   Note that the Group Replication configuration is not removed from the server instances, so you should exercise caution when reusing these in an InnoDB ClusterSet deployment, as explained in Section 8.1, “InnoDB ClusterSet Requirements”. As the instances were configured for an InnoDB ClusterSet deployment, the possibility of issues is lower, but you should be aware of the potential for configuration differences especially if the instances are reused in a different InnoDB ClusterSet deployment.

Removing a Cluster and Updating as Standalone

To remove a cluster from a ClusterSet and keep the cluster intact, as a standalone cluster, set the dissolve option to false.

The following example shows a cluster, named clustertwo, being removed intact from a ClusterSet:

          myclusterset.removeCluster('clustertwo', {dissolve: false})

If {dissolve: false} and force is not enabled, the command cannot proceed if one, or more, members are uncontactable.

If {dissolve: false, force: true}, the command proceeds even if one, or more, cluster members are uncontactable. The cluster is removed intact from the ClusterSet, but the unreachable members are not synchronized. However, if the cluster's primary is uncontactable, the cluster is dissolved to its component instances. It is not possible to keep the cluster intact if the primary is unavailable.