Documentation Home
MySQL Shell for VS Code


MySQL Shell for VS Code  /  ...  /  Cluster Class Methods

Pre-General Availability: 2024-03-18

A.2 Cluster Class Methods

The following section provides details of the options available for InnoDB Cluster methods.

Add InnoDB Cluster Instance

Adds an instance to an InnoDB Cluster.

  • JavaScript: addInstance(instance[, options])

  • Python: add_instance(instance[, options])

The options are as follows:

  • label: An identifier for the instance being added.

  • recoveryMethod: Preferred method of state recovery. May be auto, clone or incremental. The default value 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. Deprecated.

  • ipAllowlist: 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. Deprecated and ignored.

  • interactive: Boolean value used to disable or enable the wizards in the command execution, meaning 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.

Example: Add an instance to a cluster represented by the assigned variable mycluster.

mycluster.addInstance('root@localhost:3333')

For more information, see Adding Instances to an InnoDB Cluster.

Check InnoDB Cluster Instance

Verifies the instance global transaction identifier (GTID) state relating to the cluster.

  • JavaScript: checkInstanceState(instance)

  • Python: check_instance_state(instance)

Example: Analyze the instance listening on port 3334, showing the executed GTIDs with the executed and purged GTIDs on the cluster, to determine if the instance is valid for the cluster.

mycluster.checkInstanceState('root@localhost:3334')

For more information, see Adding Instances to an InnoDB Cluster.

Create InnoDB ClusterSet

Creates an InnoDB ClusterSet from an existing standalone InnoDB Cluster.

  • JavaScript: createClusterSet(dominate[, options])

  • Python: create_cluster_set(dominate[, options])

Options are as follows:

  • dryRun: Boolean, if true, all validations and steps for creating a InnoDB ClusterSet are executed, but no changes are made. An exception will be thrown when finished.

  • clusterSetReplicationSslMode: SSL mode for the InnoDB ClusterSet replication channels.

  • replicationAllowedHost: String value to use as the host name part of internal replication accounts (meaning mysql_innodb_cs_###'@'hostname). Default is %. It must be possible for any member of the InnoDB ClusterSet to connect to any other member using accounts with this host name value.

Example: Create a ClusterSet named cs1 using the variable mycluster assigned to the cluster.

mycluster.createClusterSet('cs1')

For more information, see Deploying InnoDB ClusterSet.

Describe InnoDB Cluster

  • JavaScript: describe()

  • Python: describe()

Example: Describe a cluster using the assigned variable mycluster, including all its information, replica sets, and instances.

mycluster.describe()

Disconnect InnoDB Cluster

Disconnects all internal sessions used by the cluster object.

  • JavaScript: disconnect()

  • Python: disconnect()

Example: Disconnect a cluster from all internal sessions, using the assigned variable mycluster.

mycluster.disconnect()

Dissolve InnoDB Cluster

Dissolves the cluster.

  • JavaScript: dissolve([options])

  • Python: dissolve([options])

Options are as follows:

  • 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 or enable the wizards in the command execution, meaning that prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.

Example: Stop Group Replication and unregister all of the members from the cluster metadata, using the assigned variable mycluster.

mycluster.dissolve()

Fence InnoDB Cluster

Fences an InnoDB Cluster from all traffic.

  • JavaScript: fenceAllTraffic()

  • Python: fence_all_traffic()

Example: Fence a cluster from all traffic, using the assigned variable mycluster.

mycluster.fenceAllTraffic()

For more information, see Fencing Clusters in an InnoDB ClusterSet.

Fences InnoDB Cluster from Write Traffic

Fences a cluster from Write Traffic.

  • JavaScript: fenceWrites()

  • Python: fence_writes()

Example: Fences a cluster from all write traffic, using the assigned variable mycluster.

mycluster.fenceWrites()

For more information, see Fencing Clusters in an InnoDB ClusterSet.

Restore InnoDB Cluster from Quorum Loss

Restores the cluster from quorum loss. Such a scenario can occur if a group is partitioned or more crashes than tolerable occur.

The forceQuorumUsingPartitionOf() method restores the cluster into the operational status from a loss of quorum scenario. Such a scenario can occur if a group is partitioned or more crashes than tolerable occur. When you use this method, all the online members, from the view of the given instance definition, are added to the group.

  • JavaScript: forceQuorumUsingPartitionOf(instance[, password])

  • Python: force_quorum_using_partition_of(instance[, password])

Example: Restore the cluster from quorum loss, using the assigned variable mycluster. The instance definition is the connection data for the instance.

mycluster.forceQuorumUsingPartitionOf('root@localhost:3341', 'password')

For more information, see Restoring and Rebooting an InnoDB Cluster.

Get InnoDB ClusterSet

Returns an object representing an InnoDB ClusterSet.

  • JavaScript: getClusterSet()

  • Python: get_cluster_set()

Example: Assign the InnoDB ClusterSet to a variable named myclusterset, using the assigned mycluster variable.

var myclusterset = mycluster.getClusterSet()

Get InnoDB ClusterSet Name

Retrieves the name of the InnoDB Cluster.

  • JavaScript: getName()

  • Python: get_name()

Example: Return the domain name of a cluster using the assigned variable mycluster.

mycluster.getName()

Cluster Help

Provides help about the Cluster class and its members.

  • JavaScript: help([member])

  • Python: help([member])

To see help details for fenceWrites method using the mycluster assigned variable, type:

mycluster.help("fenceWrites")

List MySQL Router

Lists the router instances.

  • JavaScript: listRouters([options])

  • Python: list_routers([options])

Options are as follows:

  • onlyUpgradeRequired: Boolean, enables filtering so only router instances that support older version of the metadata schema and require upgrade are included.

Example: Return a JSON object listing the router instances associated to the cluster, using the assigned variable mycluster.

mycluster.listRouters()

List Options

Lists the cluster configuration options for an InnoDB Cluster.

  • JavaScript: options([options])

  • Python: options([options])

Example: Return a JSON object describing the configuration options of the cluster.

mycluster.options()

Rejoin InnoDB Cluster

Rejoins an instance to the cluster.

  • JavaScript: rejoinInstance(instance[, options])

  • Python: rejoin_instance(instance[, options])

Options are as follows:

  • password: the instance connection password.

  • memberSslMode: SSL mode used on the instance.

  • interactive: Boolean value used to disable or enable the wizards in the command execution, meaning that prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.

  • ipWhitelist: The list of hosts allowed to connect to the instance for Group Replication. Deprecated.

  • ipAllowlist: The list of hosts allowed to connect to the instance for Group Replication.

Example: Rejoin the instance from the cluster using the assigned variable mycluster, including the password option.

mycluster.rejoinInstance('root@localhost:3342',{password:
'password'})

For more information, see Rejoining an Instance to a Cluster.

Removes Instance from InnoDB Cluster

Removes an Instance from an InnoDB Cluster.

  • JavaScript: removeInstance(instance[, options])

  • Python: remove_instance(instance[, options])

Options are as follows:

  • 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 or enable the wizards in the command execution, meaning that prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.

Example: Remove an instance from the cluster. In this example, the password is included as an option.

mycluster.removeInstance('root@localhost:3342',{password:
'Password1'})

For more information, see Removing Instances from an InnoDB Cluster.

Removes Metadata for a MySQL Router Instance

Removes metadata for a router instance.

  • JavaScript: removeRouterMetadata(routerDef)

  • Python: remove_router_metadata(routerDef)

Example: Remove a registered MySQL Router instance, myRouter1, from a cluster’s metadata using the assigned variable mycluster.

mycluster.removeRouterMetadata('myRouter1')

Rescan InnoDB Cluster

Rescans the InnoDB Cluster.

  • JavaScript: rescan([options])

  • Python: rescan([options])

Options are as follows:

  • 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 or enable the wizards in the command execution, meaning that 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.

  • upgradeCommProtocol: Boolean. Set to true to upgrade the Group Replication communication protocol to the highest version possible.

Example: Rescan the cluster for new and obsolete Group Replication instances, as well as changes in the used topology mode, for example, single-primary and multi-primary.

mycluster.rescan()

Reset Password of the Recovery Accounts of the InnoDB Cluster

Reset the password of the recovery accounts of an InnoDB Cluster.

  • JavaScript: resetRecoveryAccountsPassword(options)

  • Python: reset_recovery_accounts_password(options)

Options are as follows:

  • 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 or enable the wizards in the command execution, meaning that prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.

Example: Reset the passwords for all internal recovery user accounts used by the cluster.

In this example, the Boolean interactive mode is used.

mycluster.resetRecoveryAccountsPassword({interactive:true})

For more information, see User Accounts for InnoDB Cluster.

Change Option Value in an InnoDB Cluster Member

Changes the value of an option in an InnoDB Cluster member.

  • JavaScript: setInstanceOption(instance, option, value)

  • Python: set_instance_option(instance, option, value)

Options are as follows:

  • 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: String identifier of the instance.

Example: Change the memberWeight.

mycluster.setInstanceOption("root@localhost:3341","memberWeight", 95)

For more information, see Tagging Metadata.

Change Option Value in an InnoDB Cluster

Changes the value of an option for the whole of an InnoDB Cluster.

  • JavaScript: setOption(option, value)

  • Python: set_option(option, value)

Options are as follows:

  • 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: String identifier of the instance.

Example: Change the name tag of the cluster to my_new_cluster, using the assigned variable mycluster.

mycluster.setOption("clusterName", "my_new_cluster_name")

For more information, see Tagging Metadata.

Elect New Primary for InnoDB Cluster

Elects a specific InnoDB Cluster member as the new primary.

  • JavaScript: setPrimaryInstance(instance)

  • Python: set_primary_instance(instance)

Example: Set the new primary as the instance listening on port 3335, using the assigned variable of mycluster.

mycluster.setPrimaryInstance('root@localhost:3335')

For more information, see Changing the Topology of an InnoDB Cluster.

Create or Upgrade InnoDB Cluster Admin Account

Creates or upgrades an InnoDB Cluster administrator account.

  • JavaScript: setupAdminAccount(user, options)

  • Python: setup_admin_account(user, options)

Options are as follows:

  • 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 or enable the wizards in the command execution, meaning that 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.

Example: Create or upgrade a MySQL user account with the necessary privileges to administer an InnoDB Cluster, using the assigned variable of mycluster. For example, to set up a demo-user with the password Password1.

mycluster.setupAdminAccount("demo_user", {password:"Password1"})

For more information, see Creating User Accounts for AdminAPI.

Create or Upgrade a MySQL account to use with MySQL Router

Creates or upgrades a MySQL account to use with MySQL Router.

  • JavaScript: setupRouterAccount(user, options)

  • Python: setup_router_account(user, options)

Options are as follows:

  • 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 or enable the wizards in the command execution, meaning that prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.

Example: The mandatory argument user is the name of the MySQL account, to be created or upgraded, to be used by MySQL Router.

mycluster.setupRouterAccount('test@localhost:3306')

For more information, see Configuring the MySQL Router User.

Status of InnoDB Cluster

Describes the status of an InnoDB Cluster.

  • JavaScript: status([options])

  • Python: status([options])

The extended option values are:

  • 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 by Group 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).

Example: Return a JSON object describing the status of the cluster, using the assigned variable mycluster.

mycluster.status()

Switch InnoDB Cluster to Multi-Primary Mode

Changes an InnoDB Cluster running in single-primary mode to multi-primary mode.

  • JavaScript: switchToMultiPrimaryMode()

  • Python: switch_to_multi_primary_mode()

Example: Change a cluster running in single-primary mode to multi-primary mode. For example, using the assigned variable mycluster:

mycluster.switchToMultiPrimaryMode()

For more information, see Changing the Topology of an InnoDB Cluster.

Switch InnoDB Cluster to Single-Primary Mode

Switches an InnoDB Cluster to single-primary mode.

  • JavaScript: switchToSinglePrimaryMode([instance])

  • Python: switch_to_single_primary_mode([instance])

Example: Changes the host name and port number for the instance listening on port that is to be the new primary, using the mycluster assigned variable.

mycluster.switchToSinglePrimaryMode('root@localhost:3341')

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

For more information, see Changing the Topology of an InnoDB Cluster.

Unfence InnoDB Cluster

Unfences an InnoDB Cluster and resumes write traffic.

  • JavaScript: unfenceWrites()

  • Python: unfence_writes()

Example: Resume write traffic on a cluster that was previously fenced from write traffic using the mycluster assigned variable.

mycluster.unfenceWrites()

For more information, see Fencing Clusters in an InnoDB ClusterSet.