7.8.4 Rescanning a Cluster

If you make configuration changes to a cluster outside of the AdminAPI commands, for example by changing an instance's configuration manually to resolve configuration issues or after the loss of an instance, you need to update the InnoDB Cluster metadata so that it matches the current configuration of instances. In these cases, use the Cluster.rescan() operation, which enables you to update the InnoDB Cluster metadata either manually or using an interactive wizard. The Cluster.rescan() operation can detect new active instances that are not registered in the metadata and add them, or obsolete instances (no longer active) still registered in the metadata, and remove them. You can automatically update the metadata depending on the instances found by the command, or you can specify a list of instance addresses to either add to the metadata or remove from the metadata. You can also update the topology mode stored in the metadata, for example after changing from single-primary mode to multi-primary mode outside of AdminAPI.

The syntax of the command is Cluster.rescan([options]). The options dictionary supports the following:

• interactive: Boolean value used to disable or enable the wizards in the command execution. Controls whether prompts and confirmations are provided. The default value is equal to MySQL Shell wizard mode, specified by shell.options.useWizards.

• addInstances: list with the connection data of the new active instances to add to the metadata, or “auto” to automatically add missing instances to the metadata. The value “auto” is case-insensitive.

  • Instances specified in the list are added to the metadata, without prompting for confirmation

  • In interactive mode, you are prompted to confirm the addition of newly discovered instances that are not included in the addInstances option

  • In non-interactive mode, newly discovered instances that are not included in the addInstances option are reported in the output, but you are not prompted to add them

• removeInstances: list with the connection data of the obsolete instances to remove from the metadata, or “auto” to automatically remove obsolete instances from the metadata.

  • Instances specified in the list are removed from the metadata, without prompting for confirmation

  • In interactive mode, you are prompted to confirm the removal of obsolete instances that are not included in the removeInstances option

  • In non-interactive mode, obsolete instances that are not included in the removeInstances option are reported in the output but you are not prompted to remove them

• updateTopologyMode: Boolean value used to indicate if the topology mode (single-primary or multi-primary) in the metadata should be updated (true) or not (false) to match the one being used by the cluster. By default, the metadata is not updated (false).

  • If the value is true then the InnoDB Cluster metadata is compared to the current mode being used by Group Replication, and the metadata is updated if necessary. Use this option to update the metadata after making changes to the topology mode of your cluster outside of AdminAPI.

  • If the value is false then InnoDB Cluster metadata about the cluster's topology mode is not updated even if it is different from the topology used by the cluster's Group Replication group

  • If the option is not specified and the topology mode in the metadata is different from the topology used by the cluster's Group Replication group, then:

    • In interactive mode, you are prompted to confirm the update of the topology mode in the metadata

    • In non-interactive mode, if there is a difference between the topology used by the cluster's Group Replication group and the InnoDB Cluster metadata, it is reported and no changes are made to the metadata

  • When the metadata topology mode is updated to match the Group Replication mode, the auto-increment settings on all instances are updated as described at Section 7.5.7, “InnoDB Cluster and Auto-increment”.

• updateViewChangeUuid: Boolean value used to indicate if a value should be generated and set for the group_replication_view_change_uuid system variable on the cluster instances. This system variable supplies an alternative UUID for view change events generated by the group. For MySQL Server instances at release 8.0.27 and above, for an InnoDB Cluster that is part of an InnoDB ClusterSet, the group_replication_view_change_uuid system variable is required and must be set to the same value on all member servers in the cluster. From MySQL Shell 8.0.27, an InnoDB Cluster that is created using the dba.createCluster() command gets a value generated and set for the system variable on all the member servers. An InnoDB Cluster created before MySQL Shell 8.0.27 might not have the system variable set, but the InnoDB ClusterSet creation process checks for this and fails with a warning if it is absent.

  By default, updateViewChangeUuid is set to false, and if the system variable is not found or does not match on any of the instances, a warning message is returned to let you know you must set a value for the system variable and reboot the InnoDB Cluster. If you set updateViewChangeUuid to true, the rescan operation generates and sets a value for group_replication_view_change_uuid on all the member servers, following which you must reboot the cluster to implement the changes. Before MySQL Shell 8.0.29, this option is not available, and the Cluster.rescan() command automatically generates and sets the system variable value in the same way as if true was set, with a cluster reboot required afterwards to implement the changes. When you have rebooted the cluster, you can retry the InnoDB ClusterSet creation process.

• upgradeCommProtocol: Boolean value used to indicate if the Group Replication communication protocol version should be upgraded (true) or not (false) to the version supported by the instance in the cluster that is at the lowest MySQL release. By default, the communication protocol version is not upgraded (false). AdminAPI operations before MySQL Shell 8.0.26 upgraded automatically where possible, but the process can cause delays in the cluster. From MySQL Shell 8.0.26, AdminAPI operations that cause a topology change return a message if the communication protocol version can be upgraded, and you can use this option to carry out the upgrade at a suitable time. It is advisable to upgrade to the highest available version of the Group Replication communication protocol to support the latest features, such as message fragmentation for large transactions. For more information, see Setting a Group's Communication Protocol Version.

  • If the value is true then the Group Replication communication protocol version is upgraded to the version supported by the instance in the cluster that is at the lowest MySQL release.

  • If the value is false then the Group Replication communication protocol version is not upgraded.