MySQL :: MySQL Shell for VS Code :: A.4 ReplicaSet Class Methods

Add Instance to InnoDB ReplicaSet

Adds the given MySQL instance as a read-only secondary replica of the current primary of the InnoDB ReplicaSet. Replication is configured between the added instance and the primary. Replication uses an automatically created MySQL account with a random password.

JavaScript: addInstance(instance[, options])
Python: add_instance(instance[, options])

The options are as follows:

dryRun: if true, performs checks and logs changes that would be made, but does not execute them.
label: an identifier for the instance being added, used in the output of status().
recoveryMethod: Preferred method of state recovery. May be auto, clone or incremental. Default is auto.
waitRecovery: Integer value to indicate the recovery process verbosity level.
cloneDonor: host:port of an existing replica set member to clone from. IPv6 addresses are not supported for this option.
interactive: boolean value used to disable or enable the wizards in the command execution, meaning prompts and confirmations are provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.
timeout: timeout in seconds for transaction sync operations; 0 disables timeout and force the Shell to wait until the transaction sync finishes. Defaults to 0.

Example: Add an instance to the InnoDB ReplicaSet using the rs variable assigned to the ReplicaSet.

rs.addInstance('root@localhost:4430')

Describe the Status of InnoDB ReplicaSet

Describes the status of InnoDB ReplicaSet.

JavaScript: status([options])
Python: status([options])

The extended options are as follows:

0: disables the command verbosity (default).
1: includes information about the metadata version, group protocol version, group name, ReplicaSet UUIDs, ReplicaSet 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 ReplicaSet member.
Boolean: equivalent to assign either 0 (false) or 1 (true).

Example: Return a JSON object describing the status of InnoDB ReplicaSet, using the assigned variable rs.

rs.status()

Disconnects Sessions used by InnoDB ReplicaSet

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

JavaScript: disconnect()
Python: disconnect()

Example: Disconnect all internal sessions used by the ReplicaSet, assigned to the variable to rs.

rs.disconnect()

Force a Failover of the Primary of InnoDB ReplicaSet

Performs a forced failover of the primary of InnoDB ReplicaSet in disaster scenarios, where the current primary is unavailable and cannot be restored.

JavaScript: forcePrimaryInstance(instance, options)
Python: force_primary_instance(instance, options)

Options are as follows:

dryRun: If true, performs checks and log operations that would be performed, but will not execute them. The operations that would be performed can be viewed by enabling verbose output in the shell.
timeout: Integer value with the maximum number of seconds to wait until the instance being promoted catches up to the current primary.
invalidateErrorInstances: If false, aborts the failover if any instance other than the old master is unreachable or has errors. If true, such instances will not be failed over and be invalidated.

Example: Use forcePrimaryInstance, with the dryrun option set to true, to check for potential errors of a forced failover to the instance rs2:4460.

rs.forcePrimaryInstance('rs2:4460' ,{dryRun: true})

Get Name of InnoDB ReplicaSet

Returns the name of InnoDB ReplicaSet.

JavaScript: getName()
Python: get_name()

Example: Return the name of the InnoDB ReplicaSet, assigned to the variable to rs:

rs.getName()

List the InnoDB ReplicaSet Router Instances

Lists the router instances and provides information about all router instances registered for InnoDB ReplicaSet.

JavaScript: listRouters()
Python: list_routers()

The 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: List all of the registered MySQL Router instances associated to the ReplicaSet, assigned to the rs.

rs.listRouters()

Lists of InnoDB ReplicaSet Configuration Options

Returns a JSON object describing the configuration options of the InnoDB ReplicaSet.

JavaScript: options()
Python: options()

Example: List all the configuration options for the InnoDB ReplicaSet using the assigned variable rs.

rs.options()

Rejoin an instance to the InnoDB ReplicaSet

Rejoins an instance to the InnoDB ReplicaSet.

JavaScript: rejoinInstance(instance[, options])
Python: rejoin_instance(instance[, options])

Options are as follows:

dryRun: If true, performs checks and log operations that would be performed, but will not execute them.
recoveryMethod: Preferred method of state recovery. May be auto, clone or incremental. Default is auto.
waitRecovery: Integer value to indicate the recovery process verbosity level.
cloneDonor: host:port of an existing ReplicaSet member to clone from. IPv6 addresses are not supported for this option.
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.
timeout: Timeout in seconds for transaction sync operations; 0 disables timeout and force MySQL Shell to wait until the transaction sync finishes. Defaults to 0.

Example: Rejoin the instance to InnoDB ReplicaSet running on port 4450 of the local host, using the variable rs assigned to the InnoDB ReplicaSet.

rs.rejoinInstance('root@localhost:4450')

Remove an Instance from InnoDB ReplicaSet

Removes an Instance from InnoDB ReplicaSet.

JavaScript: removeInstance(instance[, options])
Python: remove_instance(instance[, options])

Options are as follows:

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.
timeout: maximum number of seconds to wait for the instance to sync up with the primary. 0 means no timeout and 0 will skip sync.

Example: Remove instance from InnoDB ReplicaSet running on port 4450 of the local host, using the variable rs assigned to the InnoDB ReplicaSet.

rs.removeInstance('root@localhost:4450')

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 ReplicaSet’s metadata using the assigned variable rs.

rs.removeRouterMetadata('myRouter1')

Change Option Value in an InnoDB ReplicaSet member.

Changes the value of an option in an InnoDB ReplicaSet 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 member of the InnoDB ReplicaSet.

Example: Change the memberWeight value.

rs.setInstanceOption("root@localhost:4430","memberWeight", 95)

For more information, see Tagging Metadata.

Set Option Value in an InnoDB ReplicaSet

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

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 InnoDB ReplicaSet.
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 InnoDB ReplicaSet after being expelled.
Label: String identifier of the instance.

Example: Set InnoDB ReplicaSet, assigned to the variable rs with the location metadata tag set to US East. Change the name tag of the ReplicaSet to new_rs, using the assigned variable rs.

rs.setOption("tag:location", "US East")

For more information, see Tagging Metadata.

Set New Primary for InnoDB ReplicaSet

Elects a specific InnoDB ReplicaSet member as the new primary.

JavaScript: setPrimaryInstance(instance)
Python: set_primary_instance(instance)

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

rs.setPrimaryInstance('root@localhost:4450')

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

Create or Upgrade InnoDB ReplicaSet Admin Account

Creates or upgrades an InnoDB ReplicaSet admin account.

JavaScript: setupAdminAccount(user, options)
Python: setup_admin_account(user, options)

Options are as follows:

password: The password for the InnoDB ReplicaSet 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 ReplicaSet, using the assigned variable of rs. For example, to set up a demo-user with the password Password1.

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

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

For more information, see Configuring the MySQL Router User.