MySQL Shell API 8.4.1
Unified development interface for MySQL Products
|
Represents an InnoDB ClusterSet. More...
Methods | |
String | getName () |
Returns the domain name of the clusterset. More... | |
Undefined | disconnect () |
Disconnects all internal sessions used by the ClusterSet object. More... | |
Cluster | createReplicaCluster (InstanceDef instance, String clusterName, Dictionary options) |
Creates a new InnoDB Cluster that is a Replica of the Primary Cluster. More... | |
Undefined | removeCluster (String clusterName, Dictionary options) |
Removes a Replica cluster from a ClusterSet. More... | |
Undefined | rejoinCluster (String clusterName, Dictionary options) |
Rejoin an invalidated Cluster back to the ClusterSet and update replication. More... | |
Undefined | setPrimaryCluster (String clusterName, Dictionary options) |
Performs a safe switchover of the PRIMARY Cluster of the ClusterSet. More... | |
Undefined | forcePrimaryCluster (String clusterName, Dictionary options) |
Performs a failover of the PRIMARY Cluster of the ClusterSet. More... | |
Dictionary | status (Dictionary options) |
Describe the status of the ClusterSet. More... | |
Dictionary | describe () |
Describe the structure of the ClusterSet. More... | |
Undefined | setRoutingOption (String router, String option, String value) |
Changes the value of either a global Routing option or of a single Router instance. More... | |
Undefined | setupAdminAccount (String user, Dictionary options) |
Create or upgrade an InnoDB ClusterSet admin account. More... | |
Undefined | setupRouterAccount (String user, Dictionary options) |
Create or upgrade a MySQL account to use with MySQL Router. More... | |
Dictionary | routingOptions (String router) |
Lists the ClusterSet Routers configuration options. More... | |
Dictionary | listRouters (String router) |
Lists the Router instances of the ClusterSet, or a single Router instance. More... | |
Undefined | setOption (String option, String value) |
Changes the value of an option for the whole ClusterSet. More... | |
Dictionary | options () |
Lists the ClusterSet configuration options. More... | |
Properties | |
String | name |
Returns the domain name of the clusterset. | |
Represents an InnoDB ClusterSet.
The clusterset object is the entry point to manage and monitor a MySQL InnoDB ClusterSet.
ClusterSets allow InnoDB Cluster deployments to achieve fault-tolerance at a whole Data Center / region or geographic location, by creating REPLICA clusters in different locations (Data Centers), ensuring Disaster Recovery is possible.
For more help on a specific function, use the \help shell command, e.g.: \help ClusterSet.createReplicaCluster
String getName | ( | ) |
Returns the domain name of the clusterset.
void disconnect | ( | ) |
Disconnects all internal sessions used by the ClusterSet object.
Disconnects the internal MySQL sessions used by the ClusterSet to query for metadata and replication information.
Cluster createReplicaCluster | ( | InstanceDef | instance, |
String | clusterName, | ||
Dictionary | options | ||
) |
Creates a new InnoDB Cluster that is a Replica of the Primary Cluster.
instance | host:port of the target instance to be used to create the Replica Cluster |
clusterName | An identifier for the REPLICA cluster to be created. |
options | optional Dictionary with additional parameters described below. |
Creates a REPLICA InnoDB cluster of the current 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 ClusterSet.
Pre-requisites
The following is a list of requirements to create a REPLICA cluster:
The Replica Cluster's name must be non-empty and no greater than 63 characters long. It can only start with an alphanumeric character or with _ (underscore), and can only contain alphanumeric, _ ( underscore), . (period), or - ( hyphen) characters.
For the detailed list of requirements to create an InnoDB Cluster, please use \? createCluster
The options dictionary can contain the following values:
The recoveryMethod option supports the following values:
If recoveryMethod is not specified 'auto' will be used by default.
The recoveryProgress option supports the following values:
By default, if the standard output on which the Shell is running refers to a terminal, the recoveryProgress option has the value of 2. Otherwise, it has the value of 1.
The cloneDonor option is used to override the automatic selection of a donor to be used when clone is selected as the recovery method. By default, a SECONDARY member will be chosen as donor. If no SECONDARY members are available the PRIMARY will be selected. The option accepts values in the format: 'host:port'. IPv6 addresses are not supported.
The memberSslMode option controls whether TLS is to be used for connections opened by Group Replication from one server to another (both recovery and group communication, in either communication stack). It also controls what kind of verification the client end of connections perform on the SSL certificate presented by the server end.
The memberSslMode option supports the following values:
If memberSslMode is not specified AUTO will be used by default.
The ipAllowlist 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 allowlist.
This option is only used and allowed when communicationStack is set to XCOM.
The groupName and localAddress are advanced options and their usage is discouraged since incorrect values can lead to Group Replication errors.
The value for groupName is used to set the Group Replication system variable 'group_replication_group_name'.
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 value of the system variable 'report_host' if defined (i.e., not 'NULL'), otherwise it is the hostname value. When the port is not specified, the default value is the port of the target instance if the communication stack in use by the Cluster is 'MYSQL', otherwise, port * 10 + 1 when the communication stack is 'XCOM'. In case the automatically determined default port value is invalid (> 65535) then an error is thrown.
The exitStateAction option supports the following values:
If exitStateAction is not specified, it defaults to OFFLINE_MODE for server versions 8.4.0 or newer, and READ_ONLY otherwise.
The consistency option supports the following values:
If consistency is not specified, it defaults to BEFORE_ON_PRIMARY_FAILOVER for server versions 8.4.0 or newer, and EVENTUAL otherwise.
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) or exhausts its auto-rejoin attempts. When set to ABORT_SERVER, the instance shuts itself down. When set to READ_ONLY the server switches itself to super-read-only mode. When set to OFFLINE_MODE it switches itself to offline mode. In this mode, connected client users are disconnected on their next request and connections are no longer accepted, with the exception of client users that have the CONNECTION_ADMIN or SUPER privilege. The exitStateAction option accepts case-insensitive string values, being the accepted values: OFFLINE_MODE (or 2), ABORT_SERVER (or 1) and READ_ONLY (or 0).
The default value is OFFLINE_MODE for server versions 8.4.0 or newer, and READ_ONLY otherwise.
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.
The value for consistency is used to set the Group Replication system variable 'group_replication_consistency' and configure the transaction consistency guarantee which a cluster provides.
When set to BEFORE_ON_PRIMARY_FAILOVER, whenever a primary failover happens in single-primary mode (default), new queries (read or write) to the newly elected primary that is applying backlog from the old primary, will be hold before execution until the backlog is applied. Special care is needed if LOCK / UNLOCK queries are used in a secondary, because the UNLOCK statement can be held. This means that, if the secondary is promoted, and transactions from the primary are being applied that target locked tables, they won't be applied and an explicit UNLOCK will also hold because the secondary needs to finish applying the transactions from the previous primary. See https://dev.mysql.com/doc/refman/en/group-replication-system-variables.html#sysvar_group_replication_consistency for more details.
When set to EVENTUAL, read queries to the new primary are allowed even if the backlog isn't applied but writes will fail (if the backlog isn't applied) due to super-read-only mode being enabled. The client may return old values.
When set to BEFORE, each transaction (RW or RO) waits until all preceding transactions are complete before starting its execution. This ensures that each transaction is executed on the most up-to-date snapshot of the data, regardless of which member it is executed on. The latency of the transaction is affected but the overhead of synchronization on RW transactions is reduced since synchronization is used only on RO transactions.
When set to AFTER, each RW transaction waits until its changes have been applied on all of the other members. This ensures that once this transaction completes, all following transactions read a database state that includes its changes, regardless of which member they are executed on. This mode shall only be used on a group that is used for predominantly RO operations to ensure that subsequent reads fetch the latest data which includes the latest writes. The overhead of synchronization on every RO transaction is reduced since synchronization is used only on RW transactions.
When set to BEFORE_AND_AFTER, each RW transaction waits for all preceding transactions to complete before being applied and until its changes have been applied on other members. A RO transaction waits for all preceding transactions to complete before execution takes place. This ensures the guarantees given by BEFORE and by AFTER. The overhead of synchronization is higher.
The consistency option accepts case-insensitive string values, being the accepted values: EVENTUAL (or 0), BEFORE_ON_PRIMARY_FAILOVER (or 1), BEFORE (or 2), AFTER (or 3), and BEFORE_AND_AFTER (or 4).
It defaults to BEFORE_ON_PRIMARY_FAILOVER for server versions 8.4.0 or newer, and EVENTUAL otherwise.
The value for expelTimeout is used to set the Group Replication system variable 'group_replication_member_expel_timeout' and configure how long Group Replication will wait before expelling from the group any members suspected of having failed. On slow networks, or when there are expected machine slowdowns, increase the value of this option. The expelTimeout option accepts positive integer values and, since 8.0.21, defaults to 5 seconds.
The value for autoRejoinTries is used to set the Group Replication system variable 'group_replication_autorejoin_tries' and configure how many times an instance will try to rejoin a Group Replication group after being expelled. In scenarios where network glitches happen but recover quickly, setting this option prevents users from having to manually add the expelled node back to the group. The autoRejoinTries option accepts positive integer values and, since 8.0.21, defaults to 3.
The value for communicationStack is used to choose which Group Replication communication stack must be used in the Cluster. It's used to set the value of the Group Replication system variable 'group_replication_communication_stack'.
When set to legacy 'XCom', all internal GCS network traffic (PAXOS and communication infrastructure) flows through a separate network address: the localAddress.
When set to 'MySQL', such traffic re-uses the existing MySQL Server facilities to establish connections among Cluster members. It allows a simpler and safer setup as it obsoletes the usage of IP allowlists (ipAllowlist), removes the explicit need to have a separate network address (localAddress), and introduces user-based authentication.
The default value for Clusters running 8.0.27+ is 'MySQL'.
The value for transactionSizeLimit is used to set the Group Replication system variable 'group_replication_transaction_size_limit' and configures the maximum transaction size in bytes which the Cluster accepts. Transactions larger than this size are rolled back by the receiving member and are not broadcast to the Cluster.
The transactionSizeLimit option accepts positive integer values and, if set to zero, there is no limit to the size of transactions the Cluster accepts
All members added or rejoined to the Cluster will use the same value.
The value for paxosSingleLeader is used to enable or disable the Group Communication engine to operate with a single consensus leader when the Cluster is in single-primary more. When enabled, the Cluster uses a single leader to drive consensus which improves performance and resilience in single-primary mode, particularly when some of the Cluster's members are unreachable.
The option is available on MySQL 8.0.31 or newer and the default value is 'OFF'.
Undefined removeCluster | ( | String | clusterName, |
Dictionary | options | ||
) |
Removes a Replica cluster from a ClusterSet.
clusterName | The name identifier of the Replica cluster to be removed. |
options | optional Dictionary with additional parameters described below. |
Removes a MySQL InnoDB Replica Cluster from the target ClusterSet.
The Cluster is removed from the ClusterSet and implicitly dissolved, i.e. each member of it becomes a standalone instance.
For the Cluster to be successfully removed from the ClusterSet the PRIMARY Cluster must be available and the ClusterSet replication channel healthy. If those conditions aren't met the Cluster can still be forcefully removed using the 'force' option, however, its Metadata won't be updated compromising the effortless usage of its members to create new Clusters and/or add to existing Clusters. To re-use those instances, the Metadata schema must be dropped using dba.dropMetadataSchema(), or the Cluster rebooted from complete outage using dba.rebootClusterFromCompleteOutage().
The options dictionary can contain the following values:
Undefined rejoinCluster | ( | String | clusterName, |
Dictionary | options | ||
) |
Rejoin an invalidated Cluster back to the ClusterSet and update replication.
clusterName | Name of the Cluster to be rejoined. |
options | optional Dictionary with additional parameters described below. |
Rejoins a Cluster that was invalidated as part of a failover or switchover, if possible. This can also be used to update replication channel in REPLICA Clusters, if it does not have the expected state, source and settings.
The PRIMARY Cluster of the ClusterSet must be reachable and available during the operation.
Pre-Requisites
The following pre-requisites are expected for Clusters rejoined to a ClusterSet. They will be automatically checked by rejoinCluster(), which will stop if any issues are found.
The following options may be given:
Undefined setPrimaryCluster | ( | String | clusterName, |
Dictionary | options | ||
) |
Performs a safe switchover of the PRIMARY Cluster of the ClusterSet.
clusterName | Name of the REPLICA cluster to be promoted. |
options | optional Dictionary with additional parameters described below. |
This command will perform a safe switchover of the PRIMARY Cluster of a ClusterSet. The current PRIMARY will be demoted to a REPLICA Cluster, while the promoted Cluster will be made the PRIMARY Cluster. All other REPLICA Clusters will be updated to replicate from the new PRIMARY.
During the switchover, the promoted Cluster will be synchronized with the old PRIMARY, ensuring that all transactions present in the PRIMARY are applied before the topology change is committed. The current PRIMARY instance is also locked with 'FLUSH TABLES WITH READ LOCK' in order to prevent changes during the switch. If either of these operations take too long or fails, the switch will be aborted.
For a switchover to be possible, all instances of the target Cluster must be reachable from the shell and have consistent transaction sets with the current PRIMARY Cluster. If the PRIMARY Cluster is not available and cannot be restored, a failover must be performed instead, using ClusterSet.forcePrimaryCluster().
The switchover will be canceled if there are REPLICA Clusters that are unreachable or unavailable. To continue, they must either be restored or invalidated by including their name in the 'invalidateReplicaClusters' option. Invalidated REPLICA Clusters must be either removed from the Cluster or restored and rejoined, using removeCluster() or rejoinCluster().
Additionally, if any available REPLICA Cluster has members that are not ONLINE and/or reachable, these members will not be in a properly configured state even after being restored and rejoined. To ensure failover works correctly, rejoinCluster() must be called on the Cluster once these members are rejoined.
The following options may be given:
Undefined forcePrimaryCluster | ( | String | clusterName, |
Dictionary | options | ||
) |
Performs a failover of the PRIMARY Cluster of the ClusterSet.
clusterName | Name of the REPLICA cluster to be promoted. |
options | optional Dictionary with additional parameters described below. |
This command will perform a failover of the PRIMARY Cluster of a ClusterSet. The target cluster is promoted to the new PRIMARY Cluster while the previous PRIMARY Cluster is invalidated. The previous PRIMARY Cluster is presumed unavailable by the Shell, but if that is not the case, it is recommended that instances of that Cluster are taken down to avoid or minimize inconsistencies.
The failover will be canceled if there are REPLICA Clusters that are unreachable or unavailable. To continue, they must either be restored or invalidated by including their name in the 'invalidateReplicaClusters' option.
Additionally, if any available REPLICA Cluster has members that are not ONLINE and/or reachable, these members will not be in a properly configured state even after being restored and rejoined. To ensure failover works correctly, rejoinCluster() must be called on the Cluster once these members are rejoined.
Note that because a failover may result in loss of transactions, it is always preferrable that the PRIMARY Cluster is restored.
Aftermath of a Failover
If a failover is the only viable option to recover from an outage, the following must be considered:
Thus, the recommended course of action in event of an outage is to always restore the PRIMARY Cluster if at all possible, even if a failover may be faster and easier in the short term.
The following options may be given:
String status | ( | Dictionary | options | ) |
Describe the status of the ClusterSet.
options | optional Dictionary with additional parameters described below. |
This function describes the status of the ClusterSet including its members (Clusters).
The function will gather state information from each member of the ClusterSet and the replication channel of it to produce a status report of the ClusterSet as a whole.
The following options may be given to control the amount of information gathered and returned.
Option 'extended' may have the following values:
shcore::Value describe | ( | void | ) |
Describe the structure of the ClusterSet.
This function describes the status of the ClusterSet including its members (Clusters).
This function describes the structure of the ClusterSet including all its information and Clusters belonging to it.
The returned JSON object contains the following attributes:
The clusters JSON object contains the following attributes:
Each instance dictionary contains the following attributes:
Undefined setRoutingOption | ( | String | router, |
String | option, | ||
String | value | ||
) |
Changes the value of either a global Routing option or of a single Router instance.
router | optional identifier of the target router instance (e.g. 192.168.45.70::system). |
option | The Router option to be changed. |
value | The value that the option shall get (or null to unset). |
The accepted options are:
The target_cluster option supports the following values:
The invalidated_cluster_policy option supports the following values:
The stats_updates_frequency option accepts positive integers and sets the frequency of updates of Router stats (timestamp, version, etc.), in seconds, in the Metadata. If set to 0 (default), no periodic updates are done. Router will round up the value to be a multiple of Router's TTL, i.e.:
If the value is null, the option value is cleared and the default value (0) takes effect.
The use_replica_primary_as_rw option accepts a boolean value to configure whether the Router should enable or disable the RW Port for the target Cluster.
When enabled, forces the RW port of Routers targeting a specific Cluster (target_cluster != 'primary') to always route to the PRIMARY of that Cluster, even when it is in a REPLICA cluster and thus, read-only. By default, the option is false and Router blocks connections to the RW port in this scenario.
The read_only_targets option supports the following values:
Undefined setupAdminAccount | ( | String | user, |
Dictionary | options | ||
) |
Create or upgrade an InnoDB ClusterSet admin account.
user | Name of the InnoDB ClusterSet administrator account. |
options | Dictionary with options for the operation. |
This function creates/upgrades a MySQL user account with the necessary privileges to administer an InnoDB ClusterSet.
This function also allows a user to upgrade an existing admin account with the necessary privileges before a dba.upgradeMetadata() call.
The mandatory argument user is the name of the MySQL account we want to create or upgrade to be used as Administrator account. The accepted format is username[@host] where the host part is optional and if not provided defaults to ''.
The options dictionary may contain the following attributes:
If the user account does not exist, either the password, requireCertIssuer or requireCertSubject are mandatory.
If the user account exists, the update option must be enabled.
If dryRun is used, the function will display information about the permissions to be granted to `user` account without actually creating and/or performing any changes to it.
To change authentication options for an existing account, set `update` to `true`. It is possible to change password without affecting certificate options or vice-versa but certificate options can only be changed together.
Undefined setupRouterAccount | ( | String | user, |
Dictionary | options | ||
) |
Create or upgrade a MySQL account to use with MySQL Router.
user | Name of the account to create/upgrade for MySQL Router. |
options | Dictionary with options for the operation. |
This function creates/upgrades a MySQL user account with the necessary privileges to be used by MySQL Router.
This function also allows a user to upgrade existing MySQL router accounts with the necessary privileges after a dba.upgradeMetadata() call.
The mandatory argument user is the name of the MySQL account we want to create or upgrade to be used by MySQL Router. The accepted format is username[@host] where the host part is optional and if not provided defaults to ''.
The options dictionary may contain the following attributes:
If the user account does not exist, either the password, requireCertIssuer or requireCertSubject are mandatory.
If the user account exists, the update option must be enabled.
If dryRun is used, the function will display information about the permissions to be granted to `user` account without actually creating and/or performing any changes to it.
To change authentication options for an existing account, set `update` to `true`. It is possible to change password without affecting certificate options or vice-versa but certificate options can only be changed together.
Dictionary routingOptions | ( | String | router | ) |
Lists the ClusterSet Routers configuration options.
router | Optional identifier of the router instance to query for the options. |
This function lists the Router configuration options of all Routers of the ClusterSet or the target Router.
Dictionary listRouters | ( | String | router | ) |
Lists the Router instances of the ClusterSet, or a single Router instance.
router | optional identifier of the target router instance (e.g. 192.168.45.70::system) |
This function lists and provides information about all Router instances registered on the Clusters members of the ClusterSet.
For each router, the following information is provided, when available:
Undefined setOption | ( | String | option, |
String | value | ||
) |
Changes the value of an option for the whole ClusterSet.
option | The option to be changed. |
value | The value that the option shall get. |
This function changes an option for the ClusterSet.
The accepted options are:
shcore::Value options | ( | ) |
Lists the ClusterSet configuration options.
This function lists the configuration options for the ClusterSet.