MySQL Shell API  8.0.21
Unified development interface for MySQL Products
Methods | Properties | List of all members
Cluster Class Reference

Represents an InnoDB cluster. More...

Methods

None add_instance (InstanceDef instance, dict options)
 Adds an Instance to the cluster. More...
 
dict check_instance_state (InstanceDef instance)
 Verifies the instance gtid state in relation to the cluster. More...
 
str describe ()
 Describe the structure of the cluster. More...
 
None disconnect ()
 Disconnects all internal sessions used by the cluster object. More...
 
None dissolve (dict options)
 Dissolves the cluster. More...
 
None force_quorum_using_partition_of (InstanceDef instance, str password)
 Restores the cluster from quorum loss. More...
 
str get_name ()
 Retrieves the name of the cluster. More...
 
dict list_routers (dict options)
 Lists the Router instances. More...
 
None rejoin_instance (InstanceDef instance, dict options)
 Rejoins an Instance to the cluster. More...
 
None remove_instance (InstanceDef instance, dict options)
 Removes an Instance from the cluster. More...
 
None rescan (dict options)
 Rescans the cluster. More...
 
None reset_recovery_accounts_password (dict options)
 Reset the password of the recovery accounts of the cluster. More...
 
str status (dict options)
 Describe the status of the cluster. More...
 
None switch_to_single_primary_mode (InstanceDef instance)
 Switches the cluster to single-primary mode. More...
 
None switch_to_multi_primary_mode ()
 Switches the cluster to multi-primary mode. More...
 
None set_primary_instance (InstanceDef instance)
 Elects a specific cluster member as the new primary. More...
 
str options (dict options)
 Lists the cluster configuration options. More...
 
None set_option (str option, str value)
 Changes the value of an option for the whole Cluster. More...
 
None set_instance_option (InstanceDef instance, str option, str value)
 Changes the value of an option in a Cluster member. More...
 
bool remove_router_metadata (RouterDef routerDef)
 Removes metadata for a router instance. More...
 
None setup_admin_account (str user, dict options)
 
Parameters
userName of the InnoDB cluster administrator account.
optionsDictionary with options for the operation.
Returns
Nothing.

This function creates/upgrades a MySQL user account with the necessary privileges to administer an InnoDB cluster.This function also allows a user to upgrade an existing admin account with the necessary privileges before a dba.upgrade_metadata() call.The mandatory argument user is the name of the MySQL account we want to create or upgrade to be used as Administrator account. The accepted format is username[@host] where the host part is optional and if not provided defaults to ''.The options dictionary may contain the following attributes:

  • password: The password for the InnoDB cluster administrator account.
  • dryRun: boolean value used to enable a dry run of the account setup process. Default value is False.
  • interactive: boolean value used to disable/enable the wizards in the command execution, i.e. prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.
  • update: boolean value that must be enabled to allow updating the privileges and/or password of existing accounts. Default value is False.

If the user account does not exist, the password is mandatory.If the user account exists, the update option must be enabled.If dryRun is used, the function will display information about the permissions to be granted to `user` account without actually creating and/or performing any changes on it.The interactive option can be used to explicitly enable or disable the interactive prompts that help the user through the account setup process.The update option must be enabled to allow updating an existing account's privileges and/or password.

Exceptions
RuntimeErrorin the following scenarios:
  • The user account name does not exist on the Cluster and update is True.
  • The user account name does not exist on the Cluster and no password was provided.
  • The user account name exists on the Cluster and update is False.
  • The account used to grant the privileges to the admin user doesn't have the necessary privileges.

 
None setup_router_account (str user, dict options)
 
Parameters
userName of the account to create/upgrade for MySQL Router.
optionsDictionary with options for the operation.
Returns
Nothing.

This function creates/upgrades a MySQL user account with the necessary privileges to be used by MySQL Router.This function also allows a user to upgrade existing MySQL router accounts with the necessary privileges after a dba.upgrade_metadata() call.The mandatory argument user is the name of the MySQL account we want to create or upgrade to be used by MySQL Router. The accepted format is username[@host] where the host part is optional and if not provided defaults to ''.The options dictionary may contain the following attributes:

  • password: The password for the MySQL Router account.
  • dryRun: boolean value used to enable a dry run of the account setup process. Default value is False.
  • interactive: boolean value used to disable/enable the wizards in the command execution, i.e. prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.
  • update: boolean value that must be enabled to allow updating the privileges and/or password of existing accounts. Default value is False.

If the user account does not exist, the password is mandatory.If the user account exists, the update option must be enabled.If dryRun is used, the function will display information about the permissions to be granted to `user` account without actually creating and/or performing any changes on it.The interactive option can be used to explicitly enable or disable the interactive prompts that help the user through the account setup process.The update option must be enabled to allow updating an existing account's privileges and/or password.

Exceptions
RuntimeErrorin the following scenarios:
  • The user account name does not exist on the Cluster and update is True.
  • The user account name does not exist on the Cluster and no password was provided.
  • The user account name exists on the Cluster and update is False.
  • The account used to grant the privileges to the router user doesn't have the necessary privileges.

 
void invalidate ()
 Mark the cluster as invalid (e.g., dissolved).
 

Properties

str name
 Retrieves the name of the cluster.
 

Detailed Description

Represents an InnoDB cluster.

Member Function Documentation

◆ add_instance()

None add_instance ( InstanceDef  instance,
dict  options 
)

Adds an Instance to the cluster.

Parameters
instanceConnection options for the target instance to be added.
optionsOptional dictionary with options for the operation.
Returns
nothing

This function adds an Instance to a InnoDB cluster.

For additional information about MySQL connection data, see Connection Data.

The options dictionary may contain the following attributes:

  • label: an identifier for the instance being added
  • recoveryMethod: Preferred method of state recovery. May be auto, clone or incremental. Default is auto.
  • waitRecovery: Integer value to indicate if the command shall wait for the recovery process to finish and its verbosity level.
  • password: the instance connection password
  • memberSslMode: SSL mode used on the instance
  • ipWhitelist: The list of hosts allowed to connect to the instance for group replication
  • localAddress: string value with the Group Replication local address to be used instead of the automatically generated one.
  • groupSeeds: string value with a comma-separated list of the Group Replication peer addresses to be used instead of the automatically generated one.
  • interactive: boolean value used to disable/enable the wizards in the command execution, i.e. prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.
  • exitStateAction: string value indicating the group replication exit state action.
  • memberWeight: integer value with a percentage weight for automatic primary election on failover.
  • autoRejoinTries: integer value to define the number of times an instance will attempt to rejoin the cluster after being expelled.

The password may be contained on the instance definition, however, it can be overwritten if it is specified on the options.

The recoveryMethod option supports the following values:

  • incremental: uses distributed state recovery, which applies missing transactions copied from another cluster member. Clone will be disabled.
  • clone: clone: uses built-in MySQL clone support, which completely replaces the state of the target instance with a full snapshot of another cluster member before distributed recovery starts. Requires MySQL 8.0.17 or newer.
  • auto: let Group Replication choose whether or not a full snapshot has to be taken, based on what the target server supports and the group_replication_clone_threshold sysvar. This is the default value. A prompt will be shown if not possible to safely determine a safe way forward. If interaction is disabled, the operation will be canceled instead.
Attention
The memberSslMode option will be removed in a future release.

The memberSslMode option supports the following values:

  • REQUIRED: if used, SSL (encryption) will be enabled for the instance to communicate with other members of the cluster
  • DISABLED: if used, SSL (encryption) will be disabled
  • AUTO: if used, SSL (encryption) will be automatically enabled or disabled based on the cluster configuration

If memberSslMode is not specified AUTO will be used by default.

The waitRecovery option supports the following values:

  • 0: do not wait and let the recovery process to finish in the background.
  • 1: block until the recovery process to finishes.
  • 2: block until the recovery process finishes and show progress information.
  • 3: block until the recovery process finishes and show progress using progress bars.

By default, if the standard output on which the Shell is running refers to a terminal, the waitRecovery option has the value of 3. Otherwise, it has the value of 2.

The exitStateAction option supports the following values:

  • ABORT_SERVER: if used, the instance shuts itself down if it leaves the cluster unintentionally or exhausts its auto-rejoin attempts.
  • READ_ONLY: if used, the instance switches itself to super-read-only mode if it leaves the cluster unintentionally or exhausts its auto-rejoin attempts.
  • OFFLINE_MODE: if used, the instance switches itself to offline mode if it leaves the cluster unintentionally or exhausts its auto-rejoin attempts. Requires MySQL 8.0.18 or newer.

If exitStateAction is not specified READ_ONLY will be used by default.

The ipWhitelist format is a comma separated list of IP addresses or subnet CIDR notation, for example: 192.168.1.0/24,10.0.0.1. By default the value is set to AUTOMATIC, allowing addresses from the instance private network to be automatically set for the whitelist.

The localAddress and groupSeeds are advanced options and their usage is discouraged since incorrect values can lead to Group Replication errors.

The value for localAddress is used to set the Group Replication system variable 'group_replication_local_address'. The localAddress option accepts values in the format: 'host:port' or 'host:' or ':port'. If the specified value does not include a colon (:) and it is numeric, then it is assumed to be the port, otherwise it is considered to be the host. When the host is not specified, the default value is the value of the system variable 'report_host' if defined (i.e., not 'NULL'), otherwise it is the hostname value. When the port is not specified, the default value is the port of the target instance * 10 + 1. In case the automatically determined default port value is invalid (> 65535) then an error is thrown.

The value for groupSeeds is used to set the Group Replication system variable 'group_replication_group_seeds'. The groupSeeds option accepts a comma-separated list of addresses in the format: 'host1:port1,...,hostN:portN'.

The value for exitStateAction is used to configure how Group Replication behaves when a server instance leaves the group unintentionally (for example after encountering an applier error) or exhausts its auto-rejoin attempts. When set to ABORT_SERVER, the instance shuts itself down. When set to READ_ONLY the server switches itself to super-read-only mode. When set to OFFLINE_MODE it switches itself to offline mode. In this mode, connected client users are disconnected on their next request and connections are no longer accepted, with the exception of client users that have the CONNECTION_ADMIN or SUPER privilege. The exitStateAction option accepts case-insensitive string values, being the accepted values: OFFLINE_MODE (or 2), ABORT_SERVER (or 1) and READ_ONLY (or 0).

The default value is READ_ONLY.

The value for memberWeight is used to set the Group Replication system variable 'group_replication_member_weight'. The memberWeight option accepts integer values. Group Replication limits the value range from 0 to 100, automatically adjusting it if a lower/bigger value is provided.

Group Replication uses a default value of 50 if no value is provided.

The value for autoRejoinTries is used to set the Group Replication system variable 'group_replication_autorejoin_tries' and configure how many times an instance will try to rejoin a Group Replication group after being expelled. In scenarios where network glitches happen but recover quickly, setting this option prevents users from having to manually add the expelled node back to the group. The autoRejoinTries option accepts positive integer values in the range [0, 2016].

The default value is 0.

Exceptions
MetadataErrorin the following scenarios:
  • If the Metadata is inaccessible.
  • If the Metadata update operation failed.
ArgumentErrorin the following scenarios:
  • If the instance parameter is empty.
  • If the instance definition is invalid.
  • If the instance definition is a connection dictionary but empty.
  • If the value for the memberSslMode option is not one of the allowed: "AUTO", "DISABLED", "REQUIRED".
  • If the value for the ipWhitelist, localAddress, groupSeeds, or exitStateAction options is empty.
  • If the instance definition cannot be used for Group Replication.
  • If the value for the waitRecovery option is not in the range [0, 3].
RuntimeErrorin the following scenarios:
  • If the instance accounts are invalid.
  • If the instance is not in bootstrapped state.
  • If the SSL mode specified is not compatible with the one used in the cluster.
  • If the value for the localAddress, groupSeeds, exitStateAction, memberWeight or autoRejoinTries options is not valid for Group Replication.
  • If the value of recoveryMethod is not auto and it cannot be used.

◆ check_instance_state()

None check_instance_state ( InstanceDef  instance)

Verifies the instance gtid state in relation to the cluster.

Parameters
instanceAn instance definition.
Returns
resultset A JSON object with the status.

Analyzes the instance executed GTIDs with the executed/purged GTIDs on the cluster to determine if the instance is valid for the cluster.

The instance definition is the connection data for the instance.

For additional information about MySQL connection data, see Connection Data.

The returned JSON object contains the following attributes:

  • state: the state of the instance
  • reason: the reason for the state reported

The state of the instance can be one of the following:

  • ok: if the instance transaction state is valid for the cluster
  • error: if the instance transaction state is not valid for the cluster

The reason for the state reported can be one of the following:

  • new: if the instance doesn't have any transactions
  • recoverable: if the instance executed GTIDs are not conflicting with the executed GTIDs of the cluster instances
  • diverged: if the instance executed GTIDs diverged with the executed GTIDs of the cluster instances
  • lost_transactions: if the instance has more executed GTIDs than the executed GTIDs of the cluster instances
Exceptions
ArgumentErrorin the following scenarios:
  • If the 'instance' parameter is empty.
  • If the 'instance' parameter is invalid.
  • If the 'instance' definition is a connection dictionary but empty.
RuntimeErrorin the following scenarios:
  • If the 'instance' is unreachable/offline.
  • If the 'instance' is a cluster member.
  • If the 'instance' belongs to a Group Replication group that is not managed as an InnoDB cluster.
  • If the 'instance' is a standalone instance but is part of a different InnoDB Cluster.
  • If the 'instance' has an unknown state.

◆ describe()

shcore::Value describe ( void  )

Describe the structure of the cluster.

Returns
A JSON object describing the structure of the cluster.

This function describes the structure of the cluster including all its information, ReplicaSets and Instances.

The returned JSON object contains the following attributes:

  • clusterName: the cluster name
  • defaultReplicaSet: the default ReplicaSet object

The defaultReplicaSet JSON object contains the following attributes:

  • name: the ReplicaSet name
  • topology: a list of dictionaries describing each instance belonging to the ReplicaSet.
  • topologyMode: the InnoDB Cluster topology mode.

Each instance dictionary contains the following attributes:

  • address: the instance address in the form of host:port
  • label: the instance name identifier
  • role: the instance role
  • version: the instance version (only available for instances >= 8.0.11)
Exceptions
MetadataErrorin the following scenarios:
  • If the Metadata is inaccessible.
RuntimeErrorin the following scenarios:
  • If the InnoDB Cluster topology mode does not match the current Group Replication configuration.
  • If the InnoDB Cluster name is not registered in the Metadata.

◆ disconnect()

void disconnect ( )

Disconnects all internal sessions used by the cluster object.

Returns
Nothing.

Disconnects the internal MySQL sessions used by the cluster to query for metadata and replication information.

◆ dissolve()

None dissolve ( dict  options)

Dissolves the cluster.

Parameters
optionsOptional parameters as described below.
Returns
Nothing.

This function stops group replication and unregisters all members from the cluster metadata.

It keeps all the user's data intact.

The options dictionary may contain the following attributes:

  • force: boolean value used to confirm that the dissolve operation must be executed, even if some members of the cluster cannot be reached or the timeout was reached when waiting for members to catch up with replication changes. By default, set to false.
  • interactive: boolean value used to disable/enable the wizards in the command execution, i.e. prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.

The force option (set to true) must only be used to dissolve a cluster with instances that are permanently not available (no longer reachable) or never to be reused again in a cluster. This allows to dissolve a cluster and remove it from the metadata, including instances than can no longer be recovered. Otherwise, the instances must be brought back ONLINE and the cluster dissolved without the force option to avoid errors trying to reuse the instances and add them back to a cluster.

Exceptions
MetadataErrorin the following scenarios:
  • If the Metadata is inaccessible.
  • If the Metadata update operation failed.

◆ force_quorum_using_partition_of()

None force_quorum_using_partition_of ( InstanceDef  instance,
str  password 
)

Restores the cluster from quorum loss.

Parameters
instanceAn instance definition to derive the forced group from.
passwordOptional string with the password for the connection.
Returns
Nothing.

This function restores the cluster back into operational status from a loss of quorum scenario. Such a scenario can occur if a group is partitioned or more crashes than tolerable occur.

The instance definition is the connection data for the instance.

For additional information about MySQL connection data, see Connection Data.

Note that this operation is DANGEROUS as it can create a split-brain if incorrectly used and should be considered a last resort. Make absolutely sure that there are no partitions of this group that are still operating somewhere in the network, but not accessible from your location.

When this function is used, all the members that are ONLINE from the point of view of the given instance definition will be added to the group.

Exceptions
ArgumentErrorin the following scenarios:
  • If the instance parameter is empty.
  • If the instance definition cannot be used for Group Replication.
RuntimeErrorin the following scenarios:
  • If the instance does not exist on the Metadata.
  • If the instance is not on the ONLINE state.
  • If the instance does is not an active member of a replication group.
  • If there are no ONLINE instances visible from the given one.
LogicErrorin the following scenarios:
  • If the cluster does not exist.

◆ get_name()

str get_name ( )

Retrieves the name of the cluster.

Returns
The name of the cluster.

◆ list_routers()

str list_routers ( dict  options)

Lists the Router instances.

Parameters
optionsOptional dictionary with options for the operation.
Returns
A JSON object listing the Router instances associated to the cluster.

This function lists and provides information about all Router instances registered for the cluster.

Whenever a Metadata Schema upgrade is necessary, the recommended process is to upgrade MySQL Router instances to the latest version before upgrading the Metadata itself, in order to minimize service disruption.

The options dictionary may contain the following attributes:

  • onlyUpgradeRequired: boolean, enables filtering so only router instances that support older version of the Metadata Schema and require upgrade are included.
Exceptions
MetadataErrorin the following scenarios:
  • If the Metadata is inaccessible.
RuntimeErrorin the following scenarios:
  • If the InnoDB Cluster topology mode does not match the current Group Replication configuration.
  • If the InnoDB Cluster name is not registered in the Metadata.

◆ rejoin_instance()

None rejoin_instance ( InstanceDef  instance,
dict  options 
)

Rejoins an Instance to the cluster.

Parameters
instanceAn instance definition.
optionsOptional dictionary with options for the operation.
Returns
Nothing.

This function rejoins an Instance to the cluster.

The instance definition is the connection data for the instance.

For additional information about MySQL connection data, see Connection Data.

The options dictionary may contain the following attributes:

  • label: an identifier for the instance being added
  • password: the instance connection password
  • memberSslMode: SSL mode used on the instance
  • ipWhitelist: The list of hosts allowed to connect to the instance for group replication

The password may be contained on the instance definition, however, it can be overwritten if it is specified on the options.

Attention
The memberSslMode option will be removed in a future release.

The memberSslMode option supports these values:

  • REQUIRED: if used, SSL (encryption) will be enabled for the instance to communicate with other members of the cluster
  • DISABLED: if used, SSL (encryption) will be disabled
  • AUTO: if used, SSL (encryption) will be automatically enabled or disabled based on the cluster configuration

If memberSslMode is not specified AUTO will be used by default.

The ipWhitelist format is a comma separated list of IP addresses or subnet CIDR notation, for example: 192.168.1.0/24,10.0.0.1. By default the value is set to AUTOMATIC, allowing addresses from the instance private network to be automatically set for the whitelist.

Exceptions
MetadataErrorin the following scenarios:
  • If the Metadata is inaccessible.
  • If the Metadata update operation failed.
ArgumentErrorin the following scenarios:
  • If the value for the memberSslMode option is not one of the allowed: "AUTO", "DISABLED", "REQUIRED".
  • If the instance definition cannot be used for Group Replication.
RuntimeErrorin the following scenarios:
  • If the instance does not exist.
  • If the instance accounts are invalid.
  • If the instance is not in bootstrapped state.
  • If the SSL mode specified is not compatible with the one used in the cluster.
  • If the instance is an active member of the cluster.

◆ remove_instance()

None remove_instance ( InstanceDef  instance,
dict  options 
)

Removes an Instance from the cluster.

Parameters
instanceAn instance definition.
optionsOptional dictionary with options for the operation.
Returns
Nothing.

This function removes an Instance from the cluster.

The instance definition is the connection data for the instance.

For additional information about MySQL connection data, see Connection Data.

The options dictionary may contain the following attributes:

  • password: the instance connection password
  • force: boolean, indicating if the instance must be removed (even if only from metadata) in case it cannot be reached. By default, set to false.
  • interactive: boolean value used to disable/enable the wizards in the command execution, i.e. prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.

The password may be contained in the instance definition, however, it can be overwritten if it is specified on the options.

The force option (set to true) must only be used to remove instances that are permanently not available (no longer reachable) or never to be reused again in a cluster. This allows to remove from the metadata an instance than can no longer be recovered. Otherwise, the instance must be brought back ONLINE and removed without the force option to avoid errors trying to add it back to a cluster.

Exceptions
MetadataErrorin the following scenarios:
  • If the Metadata is inaccessible.
  • If the Metadata update operation failed.
ArgumentErrorin the following scenarios:
  • If the instance parameter is empty.
  • If the instance definition is invalid.
  • If the instance definition is a connection dictionary but empty.
  • If the instance definition cannot be used for Group Replication.
RuntimeErrorin the following scenarios:
  • If the instance accounts are invalid.
  • If an error occurs when trying to remove the instance (e.g., instance is not reachable).

◆ rescan()

None rescan ( dict  options)

Rescans the cluster.

Parameters
optionsOptional Dictionary with options for the operation.
Returns
Nothing.

This function rescans the cluster for new and obsolete Group Replication members/instances, as well as changes in the used topology mode (i.e., single-primary and multi-primary).

The options dictionary may contain the following attributes:

  • 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.
  • interactive: boolean value used to disable/enable the wizards in the command execution, i.e. prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.
  • 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.
  • 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). Deprecated.

The value for addInstances and removeInstances is used to specify which instances to add or remove from the metadata, respectively. Both options accept list connection data. In addition, the "auto" value can be used for both options in order to automatically add or remove the instances in the metadata, without having to explicitly specify them.

Attention
The updateTopologyMode option will be removed in a future release.
Exceptions
ArgumentErrorin the following scenarios:
  • If the value for `addInstances` or `removeInstance` is empty.
  • If the value for `addInstances` or `removeInstance` is invalid.
MetadataErrorin the following scenarios:
  • If the Metadata is inaccessible.
  • If the Metadata update operation failed.
LogicErrorin the following scenarios:
  • If the cluster does not exist.
RuntimeErrorin the following scenarios:
  • If all the ReplicaSet instances of any ReplicaSet are offline.
  • If an instance specified for `addInstances` is not an active member of the replication group.
  • If an instance specified for `removeInstances` is an active member of the replication group.

◆ reset_recovery_accounts_password()

None reset_recovery_accounts_password ( dict  options)

Reset the password of the recovery accounts of the cluster.

Parameters
optionsDictionary with options for the operation.
Returns
Nothing.

This function resets the passwords for all internal recovery user accounts used by the Cluster. It can be used to reset the passwords of the recovery user accounts when needed for any security reasons. For example: periodically to follow some custom password lifetime policy, or after some security breach event.

The options dictionary may contain the following attributes:

  • force: boolean, indicating if the operation will continue in case an error occurs when trying to reset the passwords on any of the instances, for example if any of them is not online. By default, set to false.
  • interactive: boolean value used to disable/enable the wizards in the command execution, i.e. prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.

The use of the force option (set to true) is not recommended. Use it only if really needed when instances are permanently not available (no longer reachable) or never going to be reused again in a cluster. Prefer to bring the non available instances back ONLINE or remove them from the cluster if they will no longer be used.

Exceptions
RuntimeErrorin the following scenarios:
  • If some cluster instance is not ONLINE and force option not used or set to false.
  • If the recovery user account was not created by InnoDB Cluster.

◆ status()

str status ( dict  options)

Describe the status of the cluster.

Parameters
optionsOptional dictionary with options.
Returns
A JSON object describing the status of the cluster.

This function describes the status of the cluster including its ReplicaSets and Instances. The following options may be given to control the amount of information gathered and returned.

  • extended: verbosity level of the command output.
  • queryMembers: if true, connect to each Instance of the ReplicaSets to query for more detailed stats about the replication machinery.
Attention
The queryMembers option will be removed in a future release. Please use the extended option instead.

The extended option supports Integer or Boolean values:

  • 0: disables the command verbosity (default);
  • 1: includes information about the Metadata Version, Group Protocol Version, Group name, cluster member UUIDs, cluster member roles and states as reported byGroup Replication and the list of fenced system variables;
  • 2: includes information about transactions processed by connection and applier;
  • 3: includes more detailed stats about the replication machinery of each cluster member;
  • Boolean: equivalent to assign either 0 (false) or 1 (true).
Exceptions
MetadataErrorin the following scenarios:
  • If the Metadata is inaccessible.
RuntimeErrorin the following scenarios:
  • If the InnoDB Cluster topology mode does not match the current Group Replication configuration.
  • If the InnoDB Cluster name is not registered in the Metadata.

◆ switch_to_single_primary_mode()

None switch_to_single_primary_mode ( InstanceDef  instance)

Switches the cluster to single-primary mode.

Parameters
instanceOptional An instance definition.
Returns
Nothing.

This function changes a cluster running in multi-primary mode to single-primary mode.

The instance definition is the connection data for the instance.

For additional information about MySQL connection data, see Connection Data.

The instance definition is optional and is the identifier of the cluster member that shall become the new primary.

If the instance definition is not provided, the new primary will be the instance with the highest member weight (and the lowest UUID in case of a tie on member weight).

Exceptions
ArgumentErrorin the following scenarios:
  • If the instance parameter is empty.
  • If the instance definition is invalid.
RuntimeErrorin the following scenarios:
  • If 'instance' does not refer to a cluster member.
  • If any of the cluster members has a version < 8.0.13.
  • If the cluster has no visible quorum.
  • If any of the cluster members is not ONLINE.

◆ switch_to_multi_primary_mode()

void switch_to_multi_primary_mode ( void  )

Switches the cluster to multi-primary mode.

Returns
Nothing.

This function changes a cluster running in single-primary mode to multi-primary mode.

Exceptions
RuntimeErrorin the following scenarios:
  • If any of the cluster members has a version < 8.0.13.
  • If the cluster has no visible quorum.
  • If any of the cluster members is not ONLINE.

◆ set_primary_instance()

None set_primary_instance ( InstanceDef  instance)

Elects a specific cluster member as the new primary.

Parameters
instanceAn instance definition.
Returns
Nothing.

This function forces the election of a new primary, overriding any election process.

The instance definition is the connection data for the instance.

For additional information about MySQL connection data, see Connection Data.

The instance definition is mandatory and is the identifier of the cluster member that shall become the new primary.

Exceptions
ArgumentErrorin the following scenarios:
  • If the instance parameter is empty.
  • If the instance definition is invalid.
RuntimeErrorin the following scenarios:
  • If the cluster is in multi-primary mode.
  • If 'instance' does not refer to a cluster member.
  • If any of the cluster members has a version < 8.0.13.
  • If the cluster has no visible quorum.
  • If any of the cluster members is not ONLINE.

◆ options()

str options ( dict  options)

Lists the cluster configuration options.

Parameters
optionsOptional Dictionary with options.
Returns
A JSON object describing the configuration options of the cluster.

This function lists the cluster configuration options for its ReplicaSets and Instances. The following options may be given to control the amount of information gathered and returned.

  • all: if true, includes information about all group_replication system variables.
Exceptions
MetadataErrorin the following scenarios:
  • If the Metadata is inaccessible.

◆ set_option()

None set_option ( str  option,
str  value 
)

Changes the value of an option for the whole Cluster.

Parameters
optionThe option to be changed.
valueThe value that the option shall get.
Returns
Nothing.

This function changes an option for the Cluster.

The accepted options are:

  • tag:<option>: built-in and user-defined tags to be associated to the Cluster.
  • clusterName: string value to define the cluster name.
  • exitStateAction: string value indicating the group replication exit state action.
  • memberWeight: integer value with a percentage weight for automatic primary election on failover.
  • failoverConsistency: string value indicating the consistency guarantees that the cluster provides.
  • consistency: string value indicating the consistency guarantees that the cluster provides.
  • expelTimeout: integer value to define the time period in seconds that cluster members should wait for a non-responding member before evicting it from the cluster.
  • autoRejoinTries: integer value to define the number of times an instance will attempt to rejoin the cluster after being expelled.
  • disableClone: boolean value used to disable the clone usage on the cluster.
Attention
The failoverConsistency option will be removed in a future release. Please use the consistency option instead.

The value for the configuration option is used to set the Group Replication system variable that corresponds to it.

The exitStateAction option supports the following values:

  • ABORT_SERVER: if used, the instance shuts itself down if it leaves the cluster unintentionally or exhausts its auto-rejoin attempts.
  • READ_ONLY: if used, the instance switches itself to super-read-only mode if it leaves the cluster unintentionally or exhausts its auto-rejoin attempts.
  • OFFLINE_MODE: if used, the instance switches itself to offline mode if it leaves the cluster unintentionally or exhausts its auto-rejoin attempts. Requires MySQL 8.0.18 or newer.

If exitStateAction is not specified READ_ONLY will be used by default.

The consistency option supports the following values:

  • BEFORE_ON_PRIMARY_FAILOVER: if used, new queries (read or write) to the new primary will be put on hold until after the backlog from the old primary is applied.
  • EVENTUAL: if used, read queries to the new primary are allowed even if the backlog isn't applied.

If consistency is not specified, EVENTUAL will be used by default.

The value for exitStateAction is used to configure how Group Replication behaves when a server instance leaves the group unintentionally (for example after encountering an applier error) or exhausts its auto-rejoin attempts. When set to ABORT_SERVER, the instance shuts itself down. When set to READ_ONLY the server switches itself to super-read-only mode. When set to OFFLINE_MODE it switches itself to offline mode. In this mode, connected client users are disconnected on their next request and connections are no longer accepted, with the exception of client users that have the CONNECTION_ADMIN or SUPER privilege. The exitStateAction option accepts case-insensitive string values, being the accepted values: OFFLINE_MODE (or 2), ABORT_SERVER (or 1) and READ_ONLY (or 0).

The default value is READ_ONLY.

The value for memberWeight is used to set the Group Replication system variable 'group_replication_member_weight'. The memberWeight option accepts integer values. Group Replication limits the value range from 0 to 100, automatically adjusting it if a lower/bigger value is provided.

Group Replication uses a default value of 50 if no value is provided.

The value for consistency is used to set the Group Replication system variable 'group_replication_consistency' and configure the transaction consistency guarantee which a cluster provides.

When set to to BEFORE_ON_PRIMARY_FAILOVER, whenever a primary failover happens in single-primary mode (default), new queries (read or write) to the newly elected primary that is applying backlog from the old primary, will be hold before execution until the backlog is applied. When set to EVENTUAL, read queries to the new primary are allowed even if the backlog isn't applied but writes will fail (if the backlog isn't applied) due to super-read-only mode being enabled. The client may return old values.

When set to BEFORE, each transaction (RW or RO) waits until all preceding transactions are complete before starting its execution. This ensures that each transaction is executed on the most up-to-date snapshot of the data, regardless of which member it is executed on. The latency of the transaction is affected but the overhead of synchronization on RW transactions is reduced since synchronization is used only on RO transactions.

When set to AFTER, each RW transaction waits until its changes have been applied on all of the other members. This ensures that once this transaction completes, all following transactions read a database state that includes its changes, regardless of which member they are executed on. This mode shall only be used on a group that is used for predominantly RO operations to to ensure that subsequent reads fetch the latest data which includes the latest writes. The overhead of synchronization on every RO transaction is reduced since synchronization is used only on RW transactions.

When set to BEFORE_AND_AFTER, each RW transaction waits for all preceding transactions to complete before being applied and until its changes have been applied on other members. A RO transaction waits for all preceding transactions to complete before execution takes place. This ensures the guarantees given by BEFORE and by AFTER. The overhead of synchronization is higher.

The consistency option accepts case-insensitive string values, being the accepted values: EVENTUAL (or 0), BEFORE_ON_PRIMARY_FAILOVER (or 1), BEFORE (or 2), AFTER (or 3), and BEFORE_AND_AFTER (or 4).

The default value is EVENTUAL.

The value for expelTimeout is used to set the Group Replication system variable 'group_replication_member_expel_timeout' and configure how long Group Replication will wait before expelling from the group any members suspected of having failed. On slow networks, or when there are expected machine slowdowns, increase the value of this option. The expelTimeout option accepts positive integer values in the range [0, 3600].

The default value is 0.

The value for autoRejoinTries is used to set the Group Replication system variable 'group_replication_autorejoin_tries' and configure how many times an instance will try to rejoin a Group Replication group after being expelled. In scenarios where network glitches happen but recover quickly, setting this option prevents users from having to manually add the expelled node back to the group. The autoRejoinTries option accepts positive integer values in the range [0, 2016].

The default value is 0.

Tags

Tags make it possible to associate custom key/value pairs to a Cluster, storing them in its metadata. Custom tag names can be any string starting with letters and followed by letters, numbers and _. Tag values may be any JSON value. If the value is null, the tag is deleted.

Exceptions
ArgumentErrorin the following scenarios:
  • If the 'option' parameter is empty.
  • If the 'value' parameter is empty.
  • If the 'option' parameter is invalid.
RuntimeErrorin the following scenarios:
  • If any of the cluster members do not support the configuration option passed in 'option'.
  • If the value passed in 'option' is not valid for Group Replication.
  • If the cluster has no visible quorum.
  • If setting a Group Replication option and any of the cluster members is not ONLINE.

◆ set_instance_option()

None set_instance_option ( InstanceDef  instance,
str  option,
str  value 
)

Changes the value of an option in a Cluster member.

Parameters
instanceAn instance definition.
optionThe option to be changed.
valueThe value that the option shall get.
Returns
Nothing.

This function changes an option for a member of the cluster.

The instance definition is the connection data for the instance.

For additional information about MySQL connection data, see Connection Data.

The accepted options are:

  • tag:<option>: built-in and user-defined tags to be associated to the Cluster.
  • exitStateAction: string value indicating the group replication exit state action.
  • memberWeight: integer value with a percentage weight for automatic primary election on failover.
  • autoRejoinTries: integer value to define the number of times an instance will attempt to rejoin the cluster after being expelled.
  • label a string identifier of the instance.

The exitStateAction option supports the following values:

  • ABORT_SERVER: if used, the instance shuts itself down if it leaves the cluster unintentionally or exhausts its auto-rejoin attempts.
  • READ_ONLY: if used, the instance switches itself to super-read-only mode if it leaves the cluster unintentionally or exhausts its auto-rejoin attempts.
  • OFFLINE_MODE: if used, the instance switches itself to offline mode if it leaves the cluster unintentionally or exhausts its auto-rejoin attempts. Requires MySQL 8.0.18 or newer.

If exitStateAction is not specified READ_ONLY will be used by default.

The value for exitStateAction is used to configure how Group Replication behaves when a server instance leaves the group unintentionally (for example after encountering an applier error) or exhausts its auto-rejoin attempts. When set to ABORT_SERVER, the instance shuts itself down. When set to READ_ONLY the server switches itself to super-read-only mode. When set to OFFLINE_MODE it switches itself to offline mode. In this mode, connected client users are disconnected on their next request and connections are no longer accepted, with the exception of client users that have the CONNECTION_ADMIN or SUPER privilege. The exitStateAction option accepts case-insensitive string values, being the accepted values: OFFLINE_MODE (or 2), ABORT_SERVER (or 1) and READ_ONLY (or 0).

The default value is READ_ONLY.

The value for memberWeight is used to set the Group Replication system variable 'group_replication_member_weight'. The memberWeight option accepts integer values. Group Replication limits the value range from 0 to 100, automatically adjusting it if a lower/bigger value is provided.

Group Replication uses a default value of 50 if no value is provided.

The value for autoRejoinTries is used to set the Group Replication system variable 'group_replication_autorejoin_tries' and configure how many times an instance will try to rejoin a Group Replication group after being expelled. In scenarios where network glitches happen but recover quickly, setting this option prevents users from having to manually add the expelled node back to the group. The autoRejoinTries option accepts positive integer values in the range [0, 2016].

The default value is 0.

Tags

Tags make it possible to associate custom key/value pairs to a Cluster, storing them in its metadata. Custom tag names can be any string starting with letters and followed by letters, numbers and _. Tag values may be any JSON value. If the value is null, the tag is deleted.

The following pre-defined tags are available:

  • _hidden: bool - instructs the router to exclude the instance from the list of possible destinations for client applications.
  • _disconnect_existing_sessions_when_hidden: bool - instructs the router to disconnect existing connections from instances that are marked to be hidden.
    Note
    '_hidden' and '_disconnect_existing_sessions_when_hidden' can be useful to shut down the instance and perform maintenance on it without disrupting incoming application traffic.
    Exceptions
    ArgumentErrorin the following scenarios:
  • If the 'instance' parameter is empty.
  • If the 'instance' parameter is invalid.
  • If the 'instance' definition is a connection dictionary but empty.
  • If the 'option' parameter is empty.
  • If the 'value' parameter is empty.
  • If the 'option' parameter is invalid.
Exceptions
RuntimeErrorin the following scenarios:
  • If 'instance' does not refer to a cluster member.
  • If the cluster has no visible quorum.
  • If 'instance' is unreachable/offline.
  • If 'instance' does not support the configuration option passed in 'option'.
  • If the value passed in 'option' is not valid for Group Replication.

◆ remove_router_metadata()

str remove_router_metadata ( RouterDef  routerDef)

Removes metadata for a router instance.

Parameters
routerDefidentifier of the router instance to be removed (e.g. 192.168.45.70::system)
Returns
Nothing

MySQL Router automatically registers itself within the InnoDB cluster metadata when bootstrapped. However, that metadata may be left behind when instances are uninstalled or moved over to a different host. This function may be used to clean up such instances that no longer exist.

The Cluster.list_routers() function may be used to list registered router instances, including their identifier.

Exceptions
ArgumentErrorin the following scenarios:
  • if router_def is not a registered router instance