The following section provides details of the options available for InnoDB Cluster methods.
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 beauto,cloneorincremental. The default value isauto.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.
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.
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 (meaningmysql_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.
JavaScript:
describe()Python:
describe()
Example: Describe a cluster
using the assigned variable mycluster, including
all its information, replica sets, and instances.
mycluster.describe()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()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 tofalse.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()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 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.
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.
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()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()
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")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()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()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 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 tofalse.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 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')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, orautoto 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, orautoto 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 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 tofalse.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.
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.
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.
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.
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 isfalse.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 isfalse.
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.
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 isfalse.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.
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 either0(false) or1(true).
Example: Return a JSON object
describing the status of the cluster, using the assigned
variable mycluster.
mycluster.status()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.
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.
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.