MySQL Shell API 9.1.0
Unified development interface for MySQL Products
|
Represents an InnoDB ReplicaSet. More...
Methods | |
Undefined | addInstance (String instance, Dictionary options) |
Adds an instance to the replicaset. More... | |
Dictionary | describe () |
Describe the structure of the ReplicaSet. More... | |
Undefined | disconnect () |
Disconnects all internal sessions used by the replicaset object. More... | |
String | getName () |
Returns the name of the replicaset. More... | |
Dictionary | listRouters (Dictionary options) |
Lists the Router instances. More... | |
Undefined | setRoutingOption (String router, String option, String value) |
Changes the value of either a global ReplicaSet Routing option or of a single Router instance. More... | |
Dictionary | routerOptions (Dictionary options) |
Lists the configuration options of the ReplicaSet's Routers. More... | |
Dictionary | routingOptions (String router) |
Lists the ReplicaSet Routers configuration options. More... | |
Undefined | rejoinInstance (String instance, Dictionary options) |
Rejoins an instance to the replicaset. More... | |
Undefined | removeInstance (String instance, Dictionary options) |
Removes an Instance from the replicaset. More... | |
Dictionary | status (Dictionary options) |
Describe the status of the ReplicaSet. More... | |
Undefined | setPrimaryInstance (String instance, Dictionary options) |
Performs a safe PRIMARY switchover, promoting the given instance. More... | |
Undefined | forcePrimaryInstance (String instance, Dictionary options) |
Performs a failover in a replicaset with an unavailable PRIMARY. More... | |
Undefined | dissolve (Dictionary options) |
Dissolves the ReplicaSet. More... | |
Undefined | rescan (Dictionary options) |
Rescans the ReplicaSet. More... | |
Boolean | removeRouterMetadata (RouterDef routerDef) |
Removes metadata for a router instance. More... | |
Undefined | setupAdminAccount (String user, Dictionary options) |
Create or upgrade an InnoDB ReplicaSet admin account. More... | |
Undefined | setupRouterAccount (String user, Dictionary options) |
Create or upgrade a MySQL account to use with MySQL Router. More... | |
Undefined | setOption (String option, String value) |
Changes the value of an option for the whole ReplicaSet. More... | |
Undefined | setInstanceOption (String instance, String option, String value) |
Changes the value of an option in a ReplicaSet member. More... | |
Dictionary | execute (String cmd, Object instances, Dictionary options) |
Executes a SQL statement at selected instances of the ReplicaSet. More... | |
shcore::Value | options () |
Lists the ReplicaSet configuration options. More... | |
Properties | |
String | name |
Returns the name of the replicaset. | |
Represents an InnoDB ReplicaSet.
The ReplicaSet object is used to manage MySQL server topologies that use asynchronous replication. It can be created using the dba.createReplicaSet() or dba.getReplicaSet() functions.
Undefined addInstance | ( | String | instance, |
Dictionary | options | ||
) |
Adds an instance to the replicaset.
instance | host:port of the target instance to be added. |
options | Optional dictionary with options for the operation. |
This function adds the given MySQL instance as a read-only SECONDARY replica of the current PRIMARY of the replicaset. Replication will be configured between the added instance and the PRIMARY. Replication will use an automatically created MySQL account with a random password.
Once the instance is added to the replicaset, the function will wait for it to apply all pending transactions. The transaction sync may timeout if the transaction backlog is large. The timeout option may be used to increase that time.
The Shell connects to the target instance using the same username and password used to obtain the replicaset handle object. All instances of the replicaset are expected to have this same admin account with the same grants and passwords. A custom admin account with the required grants can be created while an instance is configured with dba.configureReplicaSetInstance(), but the root user may be used too.
The PRIMARY of the replicaset must be reachable and available during this operation.
Pre-Requisites
The following pre-requisites are expected for instances added to a replicaset. They will be automatically checked by addInstance(), which will stop if any issues are found.
If the selected recovery method is incremental:
If clone is available, the pre-requisites listed above can be overcome by using clone as the recovery method.
The options dictionary may 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:
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.
shcore::Value describe | ( | void | ) |
Describe the structure of the ReplicaSet.
This function describes the structure of the ReplicaSet including all its Instances.
The returned JSON object contains the following attributes:
Each instance dictionary contains the following attributes:
void disconnect | ( | ) |
Disconnects all internal sessions used by the replicaset object.
Disconnects the internal MySQL sessions used by the replicaset to query for metadata and replication information.
String getName | ( | ) |
Returns the name of the replicaset.
String listRouters | ( | Dictionary | 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 ReplicaSet.
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:
Undefined setRoutingOption | ( | String | router, |
String | option, | ||
String | value | ||
) |
Changes the value of either a global ReplicaSet 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 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.
Dictionary routerOptions | ( | Dictionary | options | ) |
Lists the configuration options of the ReplicaSet's Routers.
options | Dictionary with options for the operation. |
This function lists the Router configuration options of the ReplicaSet (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:
Dictionary routingOptions | ( | String | router | ) |
Lists the ReplicaSet 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 ReplicaSet or the target Router.
Undefined rejoinInstance | ( | String | instance, |
Dictionary | options | ||
) |
Rejoins an instance to the replicaset.
instance | host:port of the target instance to be rejoined. |
options | Optional dictionary with options for the operation. |
This function rejoins the given MySQL instance to the replicaset, making it a read-only SECONDARY replica of the current PRIMARY. Only instances previously added to the replicaset can be rejoined, otherwise the <ReplicaSet>.addInstance() function must be used to add a new instance. This can also be used to update the replication channel of instances (even if they are already ONLINE) if it does not have the expected state, source and settings.
The PRIMARY of the replicaset must be reachable and available during this operation.
Pre-Requisites
The following pre-requisites are expected for instances rejoined to a replicaset. They will be automatically checked by rejoinInstance(), which will stop if any issues are found.
If the selected recovery method is incremental:
If clone is available, the pre-requisites listed above can be overcome by using clone as the recovery method.
The options dictionary may 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:
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.
Undefined removeInstance | ( | String | instance, |
Dictionary | options | ||
) |
Removes an Instance from the replicaset.
instance | host:port of the target instance to be removed |
options | Optional dictionary with options for the operation. |
This function removes an Instance from the replicaset and stops it from replicating. The instance must not be the PRIMARY and it is expected to be reachable.
The PRIMARY of the replicaset must be reachable and available during this operation.
The instance definition is the connection data for the instance.
The options dictionary may contain the following attributes:
The force option (set to true) is required to remove instances that are unreachable. Removed instances are normally synchronized with the rest of the replicaset, so that their own copy of the metadata will be consistent and the instance will be suitable for being added back to the replicaset. When the force option is set during removal, that step will be skipped.
String status | ( | Dictionary | options | ) |
Describe the status of the ReplicaSet.
options | Optional dictionary with options. |
This function will connect to each member of the ReplicaSet and query their state, producing a status report of the ReplicaSet as a whole, as well as of its individual members.
The following options may be given to control the amount of information gathered and returned.
Option 'extended' may have the following values:
Undefined setPrimaryInstance | ( | String | instance, |
Dictionary | options | ||
) |
Performs a safe PRIMARY switchover, promoting the given instance.
instance | host:port of the target instance to be promoted. |
options | Dictionary with additional options. |
This command will perform a safe switchover of the PRIMARY of a replicaset. The current PRIMARY will be demoted to a SECONDARY and made read-only, while the promoted instance will be made a read-write master. All other SECONDARY instances will be updated to replicate from the new PRIMARY.
During the switchover, the promoted instance will be synchronized with the old PRIMARY, ensuring that all transactions present in the PRIMARY are applied before the topology change is committed. If that synchronization step takes too long or is not possible in any of the SECONDARY instances, the switch will be aborted. These problematic SECONDARY instances must be either repaired or removed from the replicaset for the fail over to be possible.
For a safe switchover to be possible, all replicaset instances must be reachable from the shell and have consistent transaction sets. If the PRIMARY is not available, a failover must be performed instead, using forcePrimaryInstance().
The following options may be given:
Undefined forcePrimaryInstance | ( | String | instance, |
Dictionary | options | ||
) |
Performs a failover in a replicaset with an unavailable PRIMARY.
instance | host:port of the target instance to be promoted. If blank, a suitable instance will be selected automatically. |
options | Dictionary with additional options. |
This command will perform a failover of the PRIMARY of a replicaset in disaster scenarios where the current PRIMARY is unavailable and cannot be restored. If given, the target instance will be promoted to a PRIMARY, while other reachable SECONDARY instances will be switched to the new PRIMARY. The target instance must have the most up-to-date GTID_EXECUTED set among reachable instances, otherwise the operation will fail. If a target instance is not given (or is null), the most up-to-date instance will be automatically selected and promoted.
After a failover, the old PRIMARY will be considered invalid by the new PRIMARY and can no longer be part of the replicaset. If the instance is still usable, it must be removed from the replicaset and re-added as a new instance. If there were any SECONDARY instances that could not be switched to the new PRIMARY during the failover, they will also be considered invalid.
Data loss is possible after a failover, because the old PRIMARY may have had transactions that were not yet replicated to the SECONDARY being promoted. Moreover, if the instance that was presumed to have failed is still able to process updates, for example because the network where it is located is still functioning but unreachable from the shell, it will continue diverging from the promoted clusters. Recovering or re-conciliating diverged transaction sets requires manual intervention and may some times not be possible, even if the failed MySQL servers can be recovered. In many cases, the fastest and simplest way to recover from a disaster that required a failover is by discarding such diverged transactions and re-provisioning a new instance from the newly promoted PRIMARY.
The following options may be given:
Undefined dissolve | ( | Dictionary | options | ) |
Dissolves the ReplicaSet.
options | Dictionary with options for the operation. |
This function stops and deletes asynchronous replication channels and unregisters all members from the ReplicaSet 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 ReplicaSet with instances that are permanently not available (no longer reachable) or never to be reused again in a ReplicaSet. This allows a ReplicaSet to be dissolved and remove it from the metadata, including instances than can no longer be recovered. Otherwise, the instances must be brought back ONLINE and the ReplicaSet dissolved without the force option to avoid errors trying to reuse the instances and add them back to a ReplicaSet.
Undefined rescan | ( | Dictionary | options | ) |
Rescans the ReplicaSet.
options | Dictionary with options for the operation. |
This function re-scans the ReplicaSet for new (already part of the replication topology but not managed in the ReplicaSet) and obsolete (no longer part of the topology) replication members/instances, as well as change to the instances configurations.
The options dictionary may contain the following attributes:
String removeRouterMetadata | ( | 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 <ReplicaSet>.listRouters() function may be used to list registered router instances, including their identifier.
Undefined setupAdminAccount | ( | String | user, |
Dictionary | options | ||
) |
Create or upgrade an InnoDB ReplicaSet admin account.
user | Name of the InnoDB ReplicaSet 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 ReplicaSet.
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.
Undefined setOption | ( | String | option, |
String | value | ||
) |
Changes the value of an option for the whole ReplicaSet.
option | The option to be changed. |
value | The value that the option shall get. |
This function changes an option for the ReplicaSet.
The accepted options are:
Tags
Tags make it possible to associate custom key/value pairs to a ReplicaSet, 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.
Undefined setInstanceOption | ( | String | instance, |
String | option, | ||
String | value | ||
) |
Changes the value of an option in a ReplicaSet member.
instance | host:port of the target instance. |
option | The option to be changed. |
value | The value that the option shall get. |
This function changes an option for a member of the ReplicaSet.
The accepted options are:
Tags
Tags make it possible to associate custom key/value pairs to a ReplicaSet, 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:
Dictionary execute | ( | String | cmd, |
Object | instances, | ||
Dictionary | options | ||
) |
Executes a SQL statement at selected instances of the ReplicaSet.
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 ReplicaSet.
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:
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 "["foo"]", then all (primary and secondary) instances are targeted, except for "foo".
shcore::Value options | ( | ) |
Lists the ReplicaSet configuration options.
This function lists the configuration options for the ReplicaSet and its instances.