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

Represents an InnoDB cluster. More...

Methods

Undefined addInstance (InstanceDef instance, Dictionary options)
 Adds an Instance to the cluster. More...
 
Dictionary checkInstanceState (InstanceDef instance, String password)
 Verifies the instance gtid state in relation with the cluster. More...
 
String describe ()
 Describe the structure of the cluster. More...
 
Undefined disconnect ()
 Disconnects all internal sessions used by the cluster object. More...
 
Undefined dissolve (Dictionary options)
 Dissolves the cluster. More...
 
Undefined forceQuorumUsingPartitionOf (InstanceDef instance, String password)
 Restores the cluster from quorum loss. More...
 
String getName ()
 Retrieves the name of the cluster. More...
 
Undefined rejoinInstance (InstanceDef instance, Dictionary options)
 Rejoins an Instance to the cluster. More...
 
Undefined removeInstance (InstanceDef instance, Dictionary options)
 Removes an Instance from the cluster. More...
 
Undefined rescan ()
 Rescans the cluster. More...
 
String status ()
 Describe the status of the cluster. More...
 
void sync_transactions (const mysqlshdk::mysql::IInstance &target_instance) const
 Synchronize transactions on target instance. More...
 
void invalidate ()
 Mark the cluster as invalid (e.g., dissolved).
 

Properties

String name
 Retrieves the name of the cluster.
 

Detailed Description

Represents an InnoDB cluster.

Member Function Documentation

◆ addInstance()

Undefined addInstance ( InstanceDef  instance,
Dictionary  options 
)

Adds an Instance to the cluster.

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

MetadataError in the following scenarios:

  • If the Metadata is inaccessible.
  • If the Metadata update operation failed. ArgumentError in 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. RuntimeError in 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, or memberWeight options is not valid for Group Replication.
Returns
nothing

This function adds an Instance to the default replica set of the cluster.

The instance definition is the connection data for the instance.

Detailed description of the connection data format is available at Connection Data.

Only TCP/IP connections are allowed for this function.

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
  • 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.
  • exitStateAction: string value indicating the group replication exit state action.
  • memberWeight: integer value with a percentage weight for automatic primary election on failover. 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 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 exitStateAction option supports the following values:
  • ABORT_SERVER: if used, the instance shuts itself down if it leaves the cluster unintentionally.
  • READ_ONLY: if used, the instance switches itself to super-read-only mode if it leaves the cluster unintentionally.
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 host of the target instance specified as argument. 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 a random value in the range [1000, 65535] is used.

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. When set to ABORT_SERVER, the instance shuts itself down, and when set to READ_ONLY the server switches itself to super-read-only mode. The exitStateAction option accepts case-insensitive string values, being the accepted values: 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.

◆ checkInstanceState()

Undefined checkInstanceState ( InstanceDef  instance,
String  password 
)

Verifies the instance gtid state in relation with the cluster.

Parameters
instanceAn instance definition.
passwordOptional string with the password for the connection.

ArgumentError in 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. RuntimeError in the following scenarios:
  • If the instance accounts are invalid.
  • If the instance is offline.
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.

Detailed description of the connection data format is available at Connection Data.

Only TCP/IP connections are allowed for this function.

The password may be contained on the instance definition, however, it can be overwritten if it is specified as a second parameter.

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

◆ describe()

String describe ( )

Describe the structure of the cluster.

MetadataError in the following scenarios:

  • If the Metadata is inaccessible.
  • If the Metadata update operation failed.
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.

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

◆ disconnect()

Undefined 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()

Undefined dissolve ( Dictionary  options)

Dissolves the cluster.

MetadataError in the following scenarios:

  • If the Metadata is inaccessible.
  • If the Metadata update operation failed.
Returns
Nothing.
Parameters
optionsOptional parameter to specify if it should deactivate replication and unregister the ReplicaSets from the cluster.

This function disables replication on the ReplicaSets, unregisters them and the the cluster from the 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.

◆ forceQuorumUsingPartitionOf()

Undefined forceQuorumUsingPartitionOf ( InstanceDef  instance,
String  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.

ArgumentError in the following scenarios:

  • If the instance parameter is empty.
  • If the instance definition cannot be used for Group Replication. RuntimeError in 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. LogicError in the following scenarios:
  • If the cluster does not exist.
Returns
Nothing.

This function restores the cluster's default replicaset 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.

Detailed description of the connection data format is available at Connection Data.

Only TCP/IP connections are allowed for this function.

The options dictionary may contain the following options:

  • mycnfPath: The path of the MySQL configuration file for the instance.
  • password: The password to get connected to the instance.
  • clusterAdmin: The name of the InnoDB cluster administrator user.
  • clusterAdminPassword: The password for the InnoDB cluster administrator account.

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

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.

◆ getName()

String getName ( )

Retrieves the name of the cluster.

Returns
The name of the cluster.

◆ rejoinInstance()

Undefined rejoinInstance ( InstanceDef  instance,
Dictionary  options 
)

Rejoins an Instance to the cluster.

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

MetadataError in the following scenarios:

  • If the Metadata is inaccessible.
  • If the Metadata update operation failed. ArgumentError in 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. RuntimeError in 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 ReplicaSet.
Returns
Nothing.

This function rejoins an Instance to the cluster.

The instance definition is the connection data for the instance.

Detailed description of the connection data format is available at Connection Data.

Only TCP/IP connections are allowed for this function.

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.

◆ removeInstance()

Undefined removeInstance ( InstanceDef  instance,
Dictionary  options 
)

Removes an Instance from the cluster.

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

MetadataError in the following scenarios:

  • If the Metadata is inaccessible.
  • If the Metadata update operation failed. ArgumentError in 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. RuntimeError in 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).
Returns
Nothing.

This function removes an Instance from the default replicaSet of the cluster.

The instance definition is the connection data for the instance.

Detailed description of the connection data format is available at Connection Data.

Only TCP/IP connections are allowed for this function.

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.

◆ rescan()

Undefined rescan ( )

Rescans the cluster.

MetadataError in the following scenarios:

  • If the Metadata is inaccessible.
  • If the Metadata update operation failed. LogicError in the following scenarios:
  • If the cluster does not exist. RuntimeError in the following scenarios:
  • If all the ReplicaSet instances of any ReplicaSet are offline.
Returns
Nothing.

This function rescans the cluster for new Group Replication members/instances.

◆ status()

String status ( )

Describe the status of the cluster.

MetadataError in the following scenarios:

  • If the Metadata is inaccessible.
  • If the Metadata update operation failed.
Returns
A JSON object describing the status of the cluster.

This function describes the status of the cluster including its ReplicaSets and Instances.

The returned JSON object contains the following attributes:

  • clusterName: the cluster name
  • defaultReplicaSet: the default ReplicaSet object
  • groupInformationSourceMember: URI of the internal connection used to obtain information about the cluster
  • metadataServer: optional, URI of the metadata server if it is different from groupInformationSourceMember
  • warning: optional, string containing any warning messages raised during execution of this operation

The defaultReplicaSet JSON object contains the following attributes:

  • name: the ReplicaSet name
  • primary: the ReplicaSet single-primary primary instance
  • ssl: the ReplicaSet SSL mode
  • status: the ReplicaSet status
  • statusText: the descriptive text of ReplicaSet status
  • topology: a dictionary of instances belonging to the ReplicaSet, where keys are instance labels and values are instance objects

Each instance is a dictionary containing the following attributes:

  • address: the instance address in the form of host:port
  • mode: the instance mode
  • readReplicas: a list of read replica Instances of the instance.
  • role: the instance role
  • status: the instance status

◆ sync_transactions()

void sync_transactions ( const mysqlshdk::mysql::IInstance &  target_instance) const

Synchronize transactions on target instance.

Wait for all current cluster transactions to be applied on the specified target instance.

Parameters
target_instanceinstance to wait for transaction to be applied.
Exceptions
RuntimeErrorif the timeout is reached when waiting for transactions to be applied.