MySQL Shell API 9.0.0
Unified development interface for MySQL Products
|
Represents an InnoDB Cluster. More...
Methods | |
None | add_instance (InstanceDef instance, dict options) |
Adds an Instance to the cluster. More... | |
ClusterSet | create_cluster_set (str domainName, dict options) |
Creates a MySQL InnoDB ClusterSet from an existing standalone InnoDB Cluster. More... | |
ClusterSet | get_cluster_set () |
Returns an object representing a ClusterSet. More... | |
dict | describe () |
Describe the structure of the Cluster. More... | |
None | disconnect () |
Disconnects all internal sessions used by the cluster object. More... | |
None | dissolve (dict options) |
Dissolves the cluster. More... | |
None | force_quorum_using_partition_of (InstanceDef instance) |
Restores the cluster from quorum loss. More... | |
str | get_name () |
Retrieves the name of the cluster. More... | |
dict | list_routers (dict options) |
Lists the Router instances. More... | |
None | set_routing_option (str router, str option, str value) |
Changes the value of either a global Cluster Routing option or of a single Router instance. More... | |
dict | router_options (dict options) |
Lists the configuration options of the Cluster's Routers. More... | |
dict | routing_options (str router) |
Lists the Cluster Routers configuration options. More... | |
dict | rejoin_instance (InstanceDef instance, dict options) |
Rejoins an Instance to the cluster. More... | |
None | remove_instance (InstanceDef instance, dict options) |
Removes an Instance from the cluster. More... | |
None | rescan (dict options) |
Rescans the cluster. More... | |
None | reset_recovery_accounts_password (dict options) |
Resets the password of the recovery and replication accounts of the Cluster. More... | |
dict | status (dict options) |
Describe the status of the Cluster. More... | |
None | switch_to_single_primary_mode (InstanceDef instance) |
Switches the cluster to single-primary mode. More... | |
None | switch_to_multi_primary_mode () |
Switches the cluster to multi-primary mode. More... | |
None | set_primary_instance (InstanceDef instance, dict options) |
Elects a specific cluster member as the new primary. More... | |
dict | options (dict options) |
Lists the cluster configuration options. More... | |
None | set_option (str option, str value) |
Changes the value of an option for the whole Cluster. More... | |
None | set_instance_option (InstanceDef instance, str option, str value) |
Changes the value of an option in a Cluster member. More... | |
bool | remove_router_metadata (RouterDef routerDef) |
Removes metadata for a router instance. More... | |
None | setup_admin_account (str user, dict options) |
Create or upgrade an InnoDB Cluster admin account. More... | |
None | setup_router_account (str user, dict options) |
Create or upgrade a MySQL account to use with MySQL Router. More... | |
None | fence_all_traffic () |
Fences a Cluster from All Traffic. More... | |
None | fence_writes () |
Fences a Cluster from Write Traffic. More... | |
None | unfence_writes () |
Unfences a Cluster. More... | |
None | add_replica_instance (InstanceDef instance, dict options) |
Adds a Read Replica Instance to the Cluster. More... | |
dict | execute (str cmd, object instances, dict options) |
Executes a SQL statement at selected instances of the Cluster. More... | |
Properties | |
str | name |
Retrieves the name of the cluster. | |
Represents an InnoDB Cluster.
The cluster object is the entry point to manage and monitor a MySQL InnoDB Cluster.
None add_instance | ( | InstanceDef | instance, |
dict | options | ||
) |
Adds an Instance to the cluster.
instance | Connection options for the target instance to be added. |
options | Optional dictionary with options for the operation. |
This function adds an Instance to a InnoDB cluster.
For additional information about MySQL connection data, see Connection Data.
The options dictionary may contain the following attributes:
The label must be non-empty and no greater than 256 characters long. It must be unique within the Cluster and can only contain alphanumeric, _ (underscore), . (period), - (hyphen), or : (colon) characters.
The recoveryMethod option supports the following values:
The recoveryProgress option supports the following values:
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 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 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 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 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 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.
ClusterSet create_cluster_set | ( | str | domainName, |
dict | options | ||
) |
Creates a MySQL InnoDB ClusterSet from an existing standalone InnoDB Cluster.
domainName | An identifier for the ClusterSet's logical dataset. |
options | Optional dictionary with additional parameters described below. |
Creates a ClusterSet object from an existing cluster, with the given data domain name.
Several checks and validations are performed to ensure that the target Cluster complies with the requirements for ClusterSets and if so, the Metadata schema will be updated to create the new ClusterSet and the target Cluster becomes the PRIMARY cluster of the ClusterSet.
InnoDB ClusterSet
A ClusterSet is composed of a single PRIMARY InnoDB Cluster that can have one or more replica InnoDB Clusters that replicate from the PRIMARY using asynchronous replication.
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.
If the PRIMARY InnoDB Cluster becomes completely unavailable, it's possible to promote a REPLICA of that cluster to take over its duties with minimal downtime or data loss.
All Cluster operations are available at each individual member (cluster) of the ClusterSet. The AdminAPI ensures all updates are performed at the PRIMARY and controls the command availability depending on the individual status of each Cluster.
Please note that InnoDB ClusterSets don't have the same consistency and data loss guarantees as InnoDB Clusters. To read more about ClusterSets, see \? ClusterSet or refer to the MySQL manual.
Pre-requisites
The following is a non-exhaustive list of requirements to create a ClusterSet:
The domainName 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.
The options dictionary can contain the following values:
The clusterSetReplicationSslMode option supports the following values:
If clusterSetReplicationSslMode is not specified, it defaults to the value of the cluster's memberSslMode option.
ReplicaSet get_cluster_set | ( | ) |
Returns an object representing a ClusterSet.
The returned object is identical to the one returned by create_cluster_set() and can be used to manage the ClusterSet.
The function will work regardless of whether the target cluster is a PRIMARY or a REPLICA Cluster, but its copy of the metadata is expected to be up-to-date.
This function will also work if the PRIMARY Cluster is unreachable or unavailable, although ClusterSet change operations will not be possible, except for failover with force_primary_cluster().
shcore::Value describe | ( | void | ) |
Describe the structure of the Cluster.
This function describes the structure of the Cluster including all its information and members.
The returned JSON object contains the following attributes:
The defaultReplicaSet JSON object contains the following attributes:
Each instance dictionary contains the following attributes:
void disconnect | ( | ) |
Disconnects all internal sessions used by the cluster object.
Disconnects the internal MySQL sessions used by the cluster to query for metadata and replication information.
None dissolve | ( | dict | options | ) |
Dissolves the cluster.
options | Optional parameters as described below. |
This function stops group replication and unregisters all members from the cluster metadata.
It keeps all the user's data intact.
The options dictionary may contain the following attributes:
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.
None force_quorum_using_partition_of | ( | InstanceDef | instance | ) |
Restores the cluster from quorum loss.
instance | An instance definition to derive the forced group from. |
This function restores the cluster 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.
For additional information about MySQL connection data, see Connection Data.
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.
str get_name | ( | ) |
Retrieves the name of the cluster.
str list_routers | ( | dict | options | ) |
Lists the Router instances.
options | Optional dictionary with options for the operation. |
This function lists and provides information about all Router instances registered for the Cluster.
For each router, the following information is provided, when available:
Whenever a Metadata Schema upgrade is necessary, the recommended process is to upgrade MySQL Router instances to the latest version before upgrading the Metadata itself, in order to minimize service disruption.
The options dictionary may contain the following attributes:
None set_routing_option | ( | str | router, |
str | option, | ||
str | value | ||
) |
Changes the value of either a global Cluster 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 read_only_targets 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 unreachable_quorum_allowed_traffic option allows configuring Router's behavior in the event of a loss of quorum on the only reachable Cluster partition. By default, Router will disconnect all existing connections and refuse new ones, but that can be configured using the following options:
This option has no practical effect if group_replication_unreachable_majority_timeout is set to a positive value and group_replication_exit_state_action is either OFFLINE_MODE or ABORT_SERVER.
dict router_options | ( | dict | options | ) |
Lists the configuration options of the Cluster's Routers.
options | Dictionary with options for the operation. |
This function lists the Router configuration options of the Cluster (global), and the Router instances. By default, only the options that can be changed from Shell (dynamic options) are displayed. Router instances with different configurations than the global ones will include the differences under their dedicated description.
The options dictionary may contain the following attributes:
The extended option supports Integer or Boolean values:
dict routing_options | ( | str | router | ) |
Lists the Cluster 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 Cluster or the target Router.
Dict rejoin_instance | ( | InstanceDef | instance, |
dict | options | ||
) |
Rejoins an Instance to the cluster.
instance | An instance definition. |
options | Optional dictionary with options for the operation. |
This function rejoins an Instance to the cluster.
The instance definition is the connection data for the instance.
For additional information about MySQL connection data, see Connection Data.
The options dictionary may contain the following attributes:
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 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 localAddress is an advanced option and its 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 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.
None remove_instance | ( | InstanceDef | instance, |
dict | options | ||
) |
Removes an Instance from the cluster.
instance | An instance definition. |
options | Optional dictionary with options for the operation. |
This function removes an Instance from the cluster.
The instance definition is the connection data for the instance.
For additional information about MySQL connection data, see Connection Data.
The options dictionary may contain the following attributes:
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.
None rescan | ( | dict | options | ) |
Rescans the cluster.
options | Optional Dictionary with options for the operation. |
This function rescans the cluster for new and obsolete Group Replication members/instances, as well as changes in the used topology mode (i.e., single-primary and multi-primary).
The options dictionary may contain the following attributes:
The value for addInstances and removeInstances is used to specify which instances to add or remove from the metadata, respectively. Both options accept list connection data. In addition, the "auto" value can be used for both options in order to automatically add or remove the instances in the metadata, without having to explicitly specify them.
'repairMetadata' is used to eliminate any inconsistencies detected in the Metadata. These inconsistencies may arise from a few scenarios, such as the failure of one or more commands. Clusters detected in the ClusterSet Metadata that do not qualify as valid members will be removed.
None reset_recovery_accounts_password | ( | dict | options | ) |
Resets the password of the recovery and replication accounts of the Cluster.
options | Dictionary with options for the operation. |
This function resets the passwords for all internal recovery user accounts used by the Cluster as well as for all replication accounts used by any Read Replica instance. It can be used to reset the passwords of the recovery or replication user accounts when needed for any security reasons. For example: periodically to follow some custom password lifetime policy, or after some security breach event.
The options dictionary may contain the following attributes:
The use of the force option (set to true) is not recommended. Use it only if really needed when instances are permanently not available (no longer reachable) or never going to be reused again in a cluster. Prefer to bring the non available instances back ONLINE or remove them from the cluster if they will no longer be used.
str status | ( | dict | options | ) |
Describe the status of the Cluster.
options | Optional dictionary with options. |
This function describes the status of the Cluster and its members. The following options may be given to control the amount of information gathered and returned.
The extended option supports Integer or Boolean values:
None switch_to_single_primary_mode | ( | InstanceDef | instance | ) |
Switches the cluster to single-primary mode.
instance | Optional An instance definition. |
This function changes a cluster running in multi-primary mode to single-primary mode.
The instance definition is the connection data for the instance.
For additional information about MySQL connection data, see Connection Data.
The instance definition is optional and is the identifier of the cluster member that shall become the new primary.
If the instance definition is not provided, the new primary will be the instance with the highest member weight (and the lowest UUID in case of a tie on member weight).
void switch_to_multi_primary_mode | ( | void | ) |
Switches the cluster to multi-primary mode.
This function changes a cluster running in single-primary mode to multi-primary mode.
None set_primary_instance | ( | InstanceDef | instance, |
dict | options | ||
) |
Elects a specific cluster member as the new primary.
instance | An instance definition. |
options | Optional dictionary with options for the operation. |
This function forces the election of a new primary, overriding any election process.
The instance definition is the connection data for the instance.
For additional information about MySQL connection data, see Connection Data.
The instance definition is mandatory and is the identifier of the cluster member that shall become the new primary.
The options dictionary may contain the following attributes:
str options | ( | dict | options | ) |
Lists the cluster configuration options.
options | Optional Dictionary with options. |
This function lists the cluster configuration options for its ReplicaSets and Instances. The following options may be given to control the amount of information gathered and returned.
None set_option | ( | str | option, |
str | value | ||
) |
Changes the value of an option for the whole Cluster.
option | The option to be changed. |
value | The value that the option shall get. |
This function changes an option for the Cluster.
The accepted options are:
The clusterName 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.
The value for the configuration option is used to set the Group Replication system variable that corresponds to it.
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 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 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.
Tags
Tags make it possible to associate custom key/value pairs to a Cluster, storing them in its metadata. Custom tag names can be any string starting with letters and followed by letters, numbers and _. Tag values may be any JSON value. If the value is null, the tag is deleted.
None set_instance_option | ( | InstanceDef | instance, |
str | option, | ||
str | value | ||
) |
Changes the value of an option in a Cluster member.
instance | An instance definition. |
option | The option to be changed. |
value | The value that the option shall get. |
This function changes an option for a member of the cluster.
The instance definition is the connection data for the instance.
For additional information about MySQL connection data, see Connection Data.
The accepted options are:
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 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 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 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.
Tags
Tags make it possible to associate custom key/value pairs to a Cluster, storing them in its metadata. Custom tag names can be any string starting with letters and followed by letters, numbers and _. Tag values may be any JSON value. If the value is null, the tag is deleted.
The following pre-defined tags are available:
The replicationSources is a comma separated list of instances (host:port) to act as sources of the replication channel, i.e. to provide source failover of the channel. The first member of the list is configured with the highest priority among all members so when the channel activates it will be chosen for the first connection attempt. By default, the source list is automatically managed by Group Replication according to the current group membership and the primary member of the Cluster is the current source for the replication channel, this is the same as setting to "primary". Alternatively, it's possible to set to "secondary" to instruct Group Replication to automatically manage the list but use a secondary member of the Cluster as source.
For the change to be effective, the Read-Replica must be reconfigured after using Cluster.rejoin_instance().
str remove_router_metadata | ( | RouterDef | routerDef | ) |
Removes metadata for a router instance.
routerDef | identifier of the router instance to be removed (e.g. 192.168.45.70::system) |
MySQL Router automatically registers itself within the InnoDB cluster metadata when bootstrapped. However, that metadata may be left behind when instances are uninstalled or moved over to a different host. This function may be used to clean up such instances that no longer exist.
The Cluster.list_routers() function may be used to list registered router instances, including their identifier.
None setup_admin_account | ( | str | user, |
dict | options | ||
) |
Create or upgrade an InnoDB Cluster admin account.
user | Name of the InnoDB Cluster 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 Cluster.
This function also allows a user to upgrade an existing admin account with the necessary privileges before a dba.upgrade_metadata() 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.
None setup_router_account | ( | str | user, |
dict | 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.upgrade_metadata() 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.
void fence_all_traffic | ( | ) |
Fences a Cluster from All Traffic.
This function fences a Cluster from all Traffic by ensuring the Group Replication is completely shut down and all members are Read-Only and in Offline mode, preventing regular client connections from connecting to it.
Use this function when performing a PRIMARY Cluster failover in a ClusterSet to prevent a split-brain.
void fence_writes | ( | ) |
Fences a Cluster from Write Traffic.
This function fences a Cluster member of a ClusterSet from all Write Traffic by ensuring all of its members are Read-Only regardless of any topology change on it. The Cluster will be put into READ ONLY mode and all members will remain available for reads. To unfence the Cluster so it restores its normal functioning and can accept all traffic use Cluster.unfenceWrites().
Use this function when performing a PRIMARY Cluster failover in a ClusterSet to allow only read traffic in the previous Primary Cluster in the event of a split-brain.
The function is not permitted on standalone Clusters.
void unfence_writes | ( | ) |
Unfences a Cluster.
This function unfences a Cluster that was previously fenced to Write traffic with Cluster.fence_writes().
None add_replica_instance | ( | InstanceDef | instance, |
dict | options | ||
) |
Adds a Read Replica Instance to the Cluster.
instance | host:port of the target instance to be added as a Read Replica. |
options | optional Dictionary with additional parameters described below. |
This function adds an Instance acting as Read-Replica of an InnoDB Cluster.
Pre-requisites
The following is a list of requirements to create a REPLICA cluster:
The options dictionary may contain the following values:
The label must be non-empty and no greater than 256 characters long. It must be unique within the Cluster and can only contain alphanumeric, _ (underscore), . (period), - (hyphen), or : (colon) characters.
The replicationSources is a comma separated list of instances (host:port) to act as sources of the replication channel, i.e. to provide source failover of the channel. The first member of the list is configured with the highest priority among all members so when the channel activates it will be chosen for the first connection attempt. By default, the source list is automatically managed by Group Replication according to the current group membership and the primary member of the Cluster is the current source for the replication channel, this is the same as setting to "primary". Alternatively, it's possible to set to "secondary" to instruct Group Replication to automatically manage the list too but use a secondary member of the Cluster as source.
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.
dict execute | ( | str | cmd, |
object | instances, | ||
dict | options | ||
) |
Executes a SQL statement at selected instances of the Cluster.
cmd | The SQL statement to execute. |
instances | The instances where cmd should be executed. |
options | Dictionary with options for the operation. |
This function allows a single MySQL SQL statement to be executed on multiple instances of the Cluster.
The 'instances' parameter can be either a string (keyword) or a list of instance addresses where cmd should be executed. If a string, the allowed keywords are:
The options dictionary may contain the following attributes:
The keyword "secondaries" / "s" is not permitted on a multi-primary Cluster.
To calculate the final list of instances where cmd should be executed, the function starts by parsing the instances parameter and then subtract from that list the ones specified in the exclude option. For example, if instances is "all" and exclude is "read-replicas", then all (primary and secondaries) instances are targeted, except the read-replicas.