8.9.4 Removing a Cluster from an InnoDB ClusterSet

If you cannot repair a cluster, you can remove it from the InnoDB ClusterSet using a clusterSet.removeCluster() command. A force option is available if the cluster cannot be contacted at all.

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 removed InnoDB Cluster cannot be added back into an InnoDB ClusterSet deployment. If you want to use the server instances in the deployment again, you will need to set up a new cluster using them.

To remove a cluster from the InnoDB ClusterSet, 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. For example:

   mysql-js> \connect admin2@127.0.0.1:4410
   Creating a session to 'admin2@127.0.0.1:4410'
   Please provide the password for 'admin2@127.0.0.1:4410': ********
   Save password for 'admin2@127.0.0.1:4410'? [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 33
   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:4410>
   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”.

   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. From MySQL Shell 8.0.28, the InnoDB Cluster is implicitly dissolved during the removal process, so that all the members become standalone instances. In MySQL Shell 8.0.27, dissolve the cluster manually following the instructions in Dissolving an InnoDB Cluster.

   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.