Documentation Home
MySQL Shell for VS Code


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

Pre-General Availability: 2024-03-18

A.3 ClusterSet Class Methods

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

Create Replica InnoDB Cluster

Creates a new InnoDB Cluster that is a replica of the primary cluster with the given cluster name and options, at the target instance.

If the target instance meets the requirements for InnoDB Cluster a new cluster is created on it, replicating from the primary instance of the primary cluster of the InnoDB ClusterSet.

  • JavaScript: createReplicaCluster(instance, clusterName[, options])

  • Python: create_replica_cluster(instance, clusterName[, options])

Options are as follows:

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

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

  • recoveryMethod: Preferred method for state recovery or provisioning. May be auto, clone, or incremental. Default is auto.

  • recoveryProgress: Integer value to indicate the recovery process verbosity level.

  • cloneDonor: Host:port of an existing member of the PRIMARY cluster to clone from. IPv6 addresses are not supported for this option.

  • manualStartOnBoot: Boolean (default false). If false, Group Replication, in cluster instances, will automatically start and rejoin when MySQL starts, otherwise, it must be started manually.

  • memberSslMode: SSL mode, used to configure the security state of the communication between the InnoDB Cluster members.

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

  • exitStateAction: String value indicating the Group Replication exit state action.

  • memberWeight: Integer value with a percentage weight for automatic primary election on failover.

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

  • timeout: Maximum number of seconds to wait for the instance to sync up with the PRIMARY cluster. Default is 0 and it means no timeout.

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

Example: Use the createReplicaCluster() method using the InnoDB ClusterSet object, assigned to the variable cs, to create the replica cluster.

cs.createReplicaCluster("127.0.0.1:4410", "cluster2")

For more information about using this method, see Deploying InnoDB ClusterSet.

Describe InnoDB ClusterSet

Describes the structure of InnoDB ClusterSet. It returns a JSON object describing the structure of the InnoDB ClusterSet.

  • JavaScript: describe()

  • Python: describe()

Example: Issue the describe() function, using the variable cs assigned to the InnoDB ClusterSet object, to view the topology of the InnoDB ClusterSet, and you do not need the status information.

cs.describe()

For more information about using this method, see InnoDB ClusterSet Status and Topology.

Disconnect InnoDB ClusterSet

Disconnects all internal sessions used by the InnoDB ClusterSet object.

  • JavaScript: disconnect()

  • Python: disconnect()

Example: Disconnect all internal sessions used by the InnoDB ClusterSet, using the assigned variable cs.

cs.disconnect()

Perform a Failover of the Primary Cluster of InnoDB ClusterSet

Performs a failover of the primary InnoDB Cluster of the InnoDB ClusterSet.

  • JavaScript: forcePrimaryCluster(clusterName[, options])

  • Python: force_primary_cluster(clusterName[, 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 MySQL Shell.

  • invalidateReplicaClusters: Lists names of replica clusters that are unreachable or unavailable that are to be invalidated during the failover.

Example: Provide the name of the replica InnoDB Cluster that will take over as the new primary cluster, and issue.

cs.forcePrimaryCluster("cluster2")

For more information about using this method, see InnoDB ClusterSet Emergency Failover.

Return Domain Name of InnoDB ClusterSet

Returns the domain name of the InnoDB ClusterSet.

  • JavaScript: getName()

  • Python: get_name()

Example: Using the cs variable assigned to the InnoDB ClusterSet object, display the domain name of the InnoDB ClusterSet.

cs.getName()

ClusterSet Help

Provides help about this class and its members.

  • JavaScript: help([member])

  • Python: help([member])

To see the help options for the InnoDB ClusterSet object, type:

\help clusterset

List MySQL Router Instances of InnoDB ClusterSet

Lists the MySQL Router instances of the InnoDB ClusterSet, or a single MySQL Router instance.

  • JavaScript: listRouters([router])

  • Python: list_routers([router])

Example: Return details of all the registered MySQL Router instances, or a router instance.

myclusterset.listRouters()

For more information about using this method, see Integrating MySQL Router With InnoDB ClusterSet.

List of InnoDB ClusterSet Configuration Options

Lists the InnoDB ClusterSet configuration options.

  • JavaScript: options()

  • Python: options()

Example: To list all the configuration options for the InnoDB ClusterSet using the assigned variable cs.

cs.options()

Rejoin InnoDB ClusterSet

Rejoins an invalidated cluster back to the InnoDB ClusterSet and updates replication.

  • JavaScript: rejoinCluster(clusterName[, options])

  • Python: rejoin_cluster(clusterName[, options])

Options are as follows:

  • dryRun: If true, will perform 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 MySQL Shell.

Example: Rejoin the Cluster to the InnoDB ClusterSet with the assigned variable cs.

cs.rejoinCluster('ClusterSet1')

For more information about using this method, see InnoDB ClusterSet Repair and Rejoin.

Remove Replica InnoDB Cluster from InnoDB ClusterSet

Removes a replica InnoDB Cluster from an InnoDB ClusterSet.

  • JavaScript: removeCluster(clusterName[, options])

  • Python: remove_cluster(clusterName[, options])

Options are as follows:

  • force: Boolean, indicating if the cluster must be removed, even if only from metadata, in case the PRIMARY cannot be reached, or the InnoDB ClusterSet replication channel cannot be found or is stopped. By default, set to false.

  • timeout: Maximum number of seconds to wait for the instance to sync up with the PRIMARY cluster. Default is 0 and it means no timeout.

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

Example: Remove a cluster, named ‘replica2’, from the InnoDB ClusterSet.

cs.removeCluster("replica2")

For more information about using this method, see Removing a Cluster from an InnoDB ClusterSet.

List of InnoDB ClusterSet Routers Configuration Options

Lists the InnoDB ClusterSet routers configuration options by returning a JSON object describing the configuration options of all router instances of the InnoDB ClusterSet and its global options, or just the specified router.

  • JavaScript: routingOptions([router])

  • Python: routing_options([router])

Example: Display the routing options that are set for each MySQL Router instance and the global policy for the IInnoDB ClusterSet deployment.

cs.routingOptions()

For more information about using this method, see Integrating MySQL Router With InnoDB ClusterSet.

Change Option Value for InnoDB ClusterSet

Changes the value of an option for the entire InnoDB ClusterSet.

  • JavaScript: setOption(option, value)

  • Python: set_option(option, value)

Option is as follows:

  • value: The value that the option will retrieve.

Example: Tag the InnoDB Cluster assigned to the variable cs with the location tag set to US East.

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

For more information about using this method, see Tagging Metadata.

Perform Switchover of the Primary InnoDB Cluster of the InnoDB ClusterSet

Performs a safe switchover of the primary InnoDB Cluster of the InnoDB ClusterSet.

  • JavaScript: setPrimaryCluster(clusterName[, options])

  • Python: set_primary_cluster(clusterName[, options])

Options are as follows:

  • dryRun: If true, will perform 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 MySQL Shell.

  • timeout: integer value to set the maximum number of seconds to wait for the synchronization of the cluster.

  • invalidateReplicaClusters: list of names of REPLICA clusters that are unreachable or unavailable that are to be invalidated during the switchover.

Example: Provide the name of the InnoDB Cluster that will take over as the new primary cluster.

cs.setPrimaryCluster('clustertwo')

For more information about using this method, see InnoDB ClusterSet Controlled Switchover.

Change Value of MySQL Router Instance

Changes the value of either a global routing option or of a single MySQL Router instance.

  • JavaScript: setRoutingOption([router], option, value)

  • Python: set_routing_option([router], option, value)

Options are as follows:

  • target_cluster: Target cluster for router's routing operations.

  • invalidated_cluster_policy: Routing policy to be taken when the target cluster is detected as being invalidated.

Example: Change the value of either a global routing option or of a single router instance.

In this example, cs is the variable for the InnoDB ClusterSet object, Rome1 is the name of the MySQL Router instance, and cluster2 is the name of the specific cluster to target.

cs.setRoutingOption('Rome1', 'target_cluster', 'cluster2')

For more information about using this method, see Integrating MySQL Router With InnoDB ClusterSet.

Describe the Status of the InnoDB ClusterSet

Describes the status of the InnoDB ClusterSet. The method gathers state information from each member of the InnoDB ClusterSet and the replication channel of it to produce a status report of the InnoDB ClusterSet as a whole.

  • JavaScript: status([options])

  • Python: status([options])

The following options may be given to control the amount of information gathered and returned. The option extended can have the following values:

  • 0: Regular level of details. Only basic information about the status of the InnoDB ClusterSet and InnoDB Cluster members.

  • 1: Includes basic information about the status of each cluster, information about each cluster member role and state as reported by Group Replication, and information about the InnoDB ClusterSet replication channel.

  • 2: Includes the list of the fenced system variables, applier worker threads, member ID, and so on. The information about the InnoDB ClusterSet replication channel is extended to include information about the applier queue size, applier queue GTID set, coordinator state, and so on.

  • 3: Includes important replication related configuration settings, such as replication delay, heartbeat delay, retry count and connection retry for the InnoDB ClusterSet replication channel.

Example: Connect to any active member of the InnoDB ClusterSet and using the assigned cs variable.

cs.status()

For more information about using this method, see InnoDB ClusterSet Status and Topology.