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

Represents an instance of MySQL InnoDB Cluster. More...

Methods

String getName ()
 Retrieves the name of the cluster. More...
 
String getAdminType ()
 Retrieves the Administration type of the cluster. More...
 
Undefined addInstance (InstanceDef instance, Dictionary options)
 Adds an Instance to the cluster. More...
 
Undefined rejoinInstance (InstanceDef instance, Dictionary options)
 Rejoins an Instance to the cluster. More...
 
Undefined removeInstance (InstanceDef instance, String password)
 Removes an Instance from 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...
 
String status ()
 Describe the status of the cluster. More...
 
Undefined dissolve (Dictionary options)
 Dissolves the cluster. More...
 
Undefined rescan ()
 Rescans the cluster. More...
 
Undefined forceQuorumUsingPartitionOf (InstanceDef instance, String password)
 Restores the cluster from quorum loss. More...
 

Properties

String name
 Cluster name.
 
String adminType
 Cluster Administration type.
 

Detailed Description

Represents an instance of MySQL InnoDB Cluster.

Member Function Documentation

◆ getName()

String getName ( )

Retrieves the name of the cluster.

Returns
The name of the cluster.

◆ getAdminType()

String getAdminType ( )

Retrieves the Administration type of the cluster.

Returns
The Administration type of the cluster.

◆ addInstance()

Undefined addInstance ( InstanceDef  instance,
Dictionary  options 
)

Adds an Instance to the cluster.

Parameters
instanceAn instance definition.
optionsOptional dictionary with options for the operation.
Exceptions
MetadataErrorif the Metadata is inaccessible.
MetadataErrorif the Metadata update operation failed.
ArgumentErrorif the instance parameter is empty.
ArgumentErrorif the instance definition is invalid.
ArgumentErrorif the instance definition is a connection dictionary but empty.
RuntimeErrorif the instance accounts are invalid.
RuntimeErrorif the instance is not in bootstrapped state.
ArgumentErrorif the value for the memberSslMode option is not one of the allowed: "AUTO", "DISABLED", "REQUIRED".
RuntimeErrorif the SSL mode specified is not compatible with the one used in the cluster.
Returns
nothing

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

The instance definition can be any of:

  • URI string.
  • Connection data dictionary.

A basic URI string has the following format: [mysql://][user[:password]@]host[:port][?sslCa=...&sslCert=...&sslKey=...]

The connection data dictionary may contain the following attributes:

  • user/dbUser: username
  • password/dbPassword: username password
  • host: hostname or IP address
  • port: port number
  • sslCat: the path to the X509 certificate authority in PEM format.
  • sslCert: The path to the X509 certificate in PEM format.
  • sslKey: The path to the X509 key in PEM format.

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.

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.

◆ rejoinInstance()

Undefined rejoinInstance ( InstanceDef  instance,
Dictionary  options 
)

Rejoins an Instance to the cluster.

Parameters
instanceAn instance definition.
optionsOptional dictionary with options for the operation.
Exceptions
MetadataErrorif the Metadata is inaccessible.
MetadataErrorif the Metadata update operation failed.
RuntimeErrorif the instance does not exist.
RuntimeErrorif the instance accounts are invalid.
RuntimeErrorif the instance is not in bootstrapped state.
ArgumentErrorif the value for the memberSslMode option is not one of the allowed: "AUTO", "DISABLED", "REQUIRED".
RuntimeErrorif the SSL mode specified is not compatible with the one used in the cluster.
Returns
nothing.

This function rejoins an Instance to the cluster.

The instance definition can be any of:

  • URI string.
  • Connection data dictionary.

A basic URI string has the following format: [mysql://][user[:password]@]host[:port][?sslCa=...&sslCert=...&sslKey=...]

The connection data dictionary may contain the following attributes:

  • user/dbUser: username
  • password/dbPassword: username password
  • host: hostname or IP address
  • port: port number
  • sslCat: the path to the X509 certificate authority in PEM format.
  • sslCert: The path to the X509 certificate in PEM format.
  • sslKey: The path to the X509 key in PEM format.

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 to be 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.

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,
String  password 
)

Removes an Instance from the cluster.

Parameters
instanceAn instance definition.
passwordOptional Instance connection password.
Exceptions
MetadataErrorif the Metadata is inaccessible.
MetadataErrorif the Metadata update operation failed.
ArgumentErrorif the instance parameter is empty.
ArgumentErrorif the instance definition is invalid.
ArgumentErrorif the instance definition is a connection dictionary but empty.
RuntimeErrorif the instance accounts are invalid
Returns
nothing.

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

The instance definition can be any of:

  • URI string.
  • Connection data dictionary.

A basic URI string has the following format: [mysql://][user[:password]@]host[:port][?sslCa=...&sslCert=...&sslKey=...]

The connection data dictionary may contain the following attributes:

  • user/dbUser: username
  • password/dbPassword: username password
  • host: hostname or IP address
  • port: port number
  • sslCat: the path to the X509 certificate authority in PEM format.
  • sslCert: The path to the X509 certificate in PEM format.
  • sslKey: The path to the X509 key in PEM format.

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

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

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 can be any of:

  • URI string.
  • Connection data dictionary.

A basic URI string has the following format: [mysql://][user[:password]@]host[:port][?sslCa=...&sslCert=...&sslKey=...]

The connection data dictionary may contain the following attributes:

  • user/dbUser: username
  • password/dbPassword: username password
  • host: hostname or IP address
  • port: port number
  • sslCat: the path to the X509 certificate authority in PEM format.
  • sslCert: The path to the X509 certificate in PEM format.
  • sslKey: The path to the X509 key in PEM format.

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.

Exceptions
MetadataErrorif the Metadata is inaccessible.
MetadataErrorif 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 default replicaSet name
  • instances: a List of dictionaries describing each instance belonging to the Default ReplicaSet. Each instance dictionary contains the following attributes:
  • label: the instance name identifier
  • host: the instance hostname and IP address in the form of host:port
  • role: the instance role

◆ status()

String status ( )

Describe the status of the cluster.

Exceptions
MetadataErrorif the Metadata is inaccessible.
MetadataErrorif 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 The defaultReplicaSet JSON object contains the following attributes:
  • name: the default replicaSet name
  • primary: the Default ReplicaSet single-master primary instance
  • status: the Default ReplicaSet status
  • statusText: the Default ReplicaSet status descriptive text Each instance is dictionary containing the following attributes:
  • label: the instance name identifier
  • address: the instance hostname and IP address in the form of host:port
  • status: the instance status
  • role: the instance role
  • mode: the instance mode
  • readReplicas: a List of read replica Instances of the instance.

◆ dissolve()

Undefined dissolve ( Dictionary  options)

Dissolves the cluster.

Exceptions
MetadataErrorif the Metadata is inaccessible.
MetadataErrorif 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 following is the only option supported:

  • force: boolean, confirms that the dissolve operation must be executed.

◆ rescan()

Undefined rescan ( )

Rescans the cluster.

Exceptions
MetadataErrorif the Metadata is inaccessible.
MetadataErrorif the Metadata update operation failed.
LogicErrorif the cluster does not exist.
RuntimeErrorif all the ReplicaSet instances of any ReplicaSet are offline.
Returns
nothing.

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

◆ 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.
Exceptions
MetadataErrorif the instance parameter is empty.
ArgumentErrorif the instance parameter is empty.
RuntimeErrorif the instance does not exist on the Metadata.
RuntimeErrorif the instance is not on the ONLINE state.
RuntimeErrorif the instance does is not an active member of a replication group.
RuntimeErrorif there are no ONLINE instances visible from the given one.
LogicErrorif 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.

A basic URI string has the following format: [mysql://][user[:password]@]host[:port][?sslCa=...&sslCert=...&sslKey=...]

The connection data dictionary may contain the following attributes:

  • user/dbUser: username
  • password/dbPassword: username password
  • host: hostname or IP address
  • port: port number
  • sslCat: the path to the X509 certificate authority in PEM format.
  • sslCert: The path to the X509 certificate in PEM format.
  • sslKey: The path to the X509 key in PEM format.

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.