datasource
The datasource command affects a single data source.
datasource [ds-name] [sub-command]
The following sub-commands are available:
| Option | Description | Version |
|---|---|---|
backup | Backup a datasource. | |
connections | Displays the current number of connections running to the given node through connectors. Valid: -l | 7.0.2 |
drain | Prevents new connection to be made to the given data source, while ongoing connection remain untouched. If a timeout (in seconds) is given, ongoing connections will be severed only after the timeout expires. | 7.0.2 |
fail | Fail a datasource. | |
offline | Put a datasource into the offline state. | |
online | Put a datasource into the online state. | |
recover | Recover a datasource into an operational state as a replica. | |
restore | Restore a datasource from a previous backup. | |
shun | Shun a datasource. | |
slave | Set the datasource to be a slave. THe datasource must be OFFLINE, FAILED or SHUNNED for this command to work. | |
welcome | Welcome a shunned datasource back to the cluster. |
datasource backup
datasource [ds-name] backup [sub-command]
The datasource backup command invokes a backup on the data source on the named host using the
default backup agent and storage agent. Backups taken in this way can be reloaded using the datasource restore command.
The following command options are supported:
| Option | Description | Version |
|---|---|---|
backupagent | Specify the backup agent to use. | |
storageagent | Specify the storage agent to use. | |
timeout | Number of seconds to wait before the command times out. |
On success the backup URL will be written to the console.
The following example performs a backup on host saturn using the default backup agent.
cctrl> datasource saturn backup
The following example performs a backup on host mercury using the xtrabackup agent, which is named explicitly.
cctrl> datasource mercury backup xtrabackup
datasource connections
Available in 7.0.2 and later.
The datasource connections command displays the current number of connections running to the
given node through connectors.
The optional -l flag will add the list of connectors and their number of connections to this node.
Example:
[LOGICAL] /nyc > datasource db2 connections -l
15
connector@db3[16305] (10)
connector@db2[20304] (5)
datasource drain
Available in 7.0.2 and later.
The datasource drain command will prevent new connections to the specified data source, while ongoing connections
remain untouched.
If a timeout (in seconds) is given, ongoing connections will be severed after the timeout expires.
This command returns immediately, no matter whether a timeout is given or not. The number of remaining connections can be displayed
with the datasource connections command.
This command will typically be used for seamless node maintenance, including composite data source (whole site) maintenance.
Under the hood, this command will put the data source into SHUNNED state, with lastShunReason set to
DRAIN-CONNECTIONS. Once the maintenance is finished and willing to re-allow connections to it, the command
datasource welcome will bring the data source (and its underlying physical nodes if applicable) back to an
ONLINE operational state.
Example:
[LOGICAL] /nyc > datasource db2 drain
DataSource 'db2@nyc' set to SHUNNED
[LOGICAL] /nyc > ls
COORDINATOR[db1:AUTOMATIC:ONLINE]
ROUTERS:
+---------------------------------------------------------------------------------+
|connector@db1[15937](ONLINE, created=58, active=10) |
|connector@db2[20304](ONLINE, created=29, active=5) |
|connector@db3[16305](ONLINE, created=20, active=10) |
|connector@db4[15065](ONLINE, created=0, active=0) |
|connector@db5[15172](ONLINE, created=0, active=0) |
|connector@db6[15261](ONLINE, created=0, active=0) |
+---------------------------------------------------------------------------------+
DATASOURCES:
+---------------------------------------------------------------------------------+
|db1(master:ONLINE, progress=189240, THL latency=0.492) |
|STATUS [OK] [2022/11/17 01:21:10 PM UTC] |
+---------------------------------------------------------------------------------+
| MANAGER(state=ONLINE) |
| REPLICATOR(role=master, state=ONLINE) |
| DATASERVER(state=ONLINE |
| CONNECTIONS(created=59, active=10) |
+---------------------------------------------------------------------------------+
+---------------------------------------------------------------------------------+
|db2(slave:SHUNNED(DRAIN-CONNECTIONS), progress=102621, latency=172.826) |
|STATUS [SHUNNED] [2022/11/17 02:12:59 PM UTC] |
+---------------------------------------------------------------------------------+
| MANAGER(state=ONLINE) |
| REPLICATOR(role=slave, master=db1, state=ONLINE) |
| DATASERVER(state=ONLINE) |
| CONNECTIONS(created=6, active=0) |
+---------------------------------------------------------------------------------+
+---------------------------------------------------------------------------------+
|db3(slave:ONLINE, progress=155889, latency=67.533) |
|STATUS [OK] [2022/11/17 01:21:39 PM UTC] |
+---------------------------------------------------------------------------------+
| MANAGER(state=ONLINE) |
| REPLICATOR(role=slave, master=db1, state=ONLINE) |
| DATASERVER(state=ONLINE) |
| CONNECTIONS(created=42, active=10) |
+---------------------------------------------------------------------------------+
datasource fail
The datasource fail allows you to place a host into the failed state.
To place a node back into an online state, you must issue the datasource recover command.
If the cluster is in AUTOMATIC policy mode, the cluster will attempt to recover the host automatically if the replicator and database are online.
In order to maintain the failed state, switch the cluster to MAINTENANCE and/or stop the underlying database and replicator.
The following example changes the state of the node venus, to failed:
cctrl> datasource venus fail
datasource offline
The datasource offline allows you to place a host into an offline state. It has no effect if the
datasource is already in an offline state.
To place a node back into an online state, you must issue the datasource online command.
If the cluster is in AUTOMATIC policy mode, the cluster will return the host to online automatically.
In order to maintain the offline state, switch the cluster to MAINTENANCE and/or stop the underlying database and replicator.
The following example changes the state of the node mercury, to offline:
cctrl> datasource mercury offline
datasource online
The datasource online allows you to place a host into an online state. It has no effect if the
datasource is already in an online state.
To place a node back into an offline state, you must issue the datasource offline command.
If the node is in a SHUNNED or FAILED state, this command will fail with an error.
Instead, you should use the datasource recover command.
The following example changes the state of the node mercury, to online:
cctrl> datasource mercury online
datasource recover
The datasource recover reconfigures a shunned data source and returns it to the cluster as a
replica. This command can be used with failed primary as well as failed replica data sources.
For replica data sources, the recover command attempts to restart the DBMS server followed by replication. If successful, the data source joins the cluster as an online replica.
For primary data sources, the recover command first reconfigures the primary as a replica. It then performs the same recovery process as for a failed replica.
If datasource recover is unsuccessful, the next step is typically to restore the data source
from a backup, or re-provision from a viable source. This should enable it to rejoin the cluster as a normal replica.
The following example recovers host mercury following a failure. The command is identical for primary and replica data sources.
cctrl> datasource mercury recover
datasource restore
The datasource restore command reloads a backup generated with the datasource backup command.
The following command options are supported:
uri- The URI of a specific backup to restoretimeout- Number of seconds to wait before the command times out.
To restore a data source you must first put the data source and its associated replicator offline.
The following example restores host saturn from the latest backup. The preceding commands place the datasource and replicator offline. The commands after the restore return the datasource to the cluster and put it online.
cctrl> datasource saturn shun
cctrl> datasource saturn offline
cctrl> replicator saturn offline
cctrl> datasource saturn restore
cctrl> datasource saturn welcome
cctrl> cluster online
The following example restores host mercury from an existing backup, which is explicitly named. The datasource and replicator must be offline.
cctrl> datasource mercury restore storage://file-system/store-0000000004.properties
datasource slave
The datasource slave is used to set the role of a given datasource to a slave.
The datasource must be either OFFLINE,FAILED or SHUNNED for this command to work.
datasource shun
The datasource shun command removes the data source from the cluster and makes it unavailable to
applications. It will remain in the shunned state without further changes until you issue a datasource welcome or
datasource recover command.
The datasource shun command is most commonly used to perform maintenance on a data source. It allows
you to reboot servers and replicators without triggering automated policy mode rules.
The following example shuns the data source on host venus.
cctrl> datasource venus shun
datasource welcome
When a datasource has been shunned, the datasource can be welcomed back to the dataservice by using the
datasource welcome command. The datasource welcome command attempts to
enable the datasource in the ONLINE state using the current roles and configuration. If the datasource
was operating as a replica before it was shunned, the welcome command will enable the
datasource as a replica.
For example, the host host3 is a replica and currently online:
+----------------------------------------------------------------------------+
|host3(slave:ONLINE, progress=157454, latency=1.000) |
|STATUS [OK] [2013/05/14 05:12:52 PM BST] |
+----------------------------------------------------------------------------+
| MANAGER(state=ONLINE) |
| REPLICATOR(role=slave, master=host2, state=ONLINE) |
| DATASERVER(state=ONLINE) |
| CONNECTIONS(created=0, active=0) |
+----------------------------------------------------------------------------+
[LOGICAL:EXPERT] /alpha > datasource host3 shun
DataSource 'host3' set to SHUNNED
To switch the datasource back to the online state, the datasource welcome is used:
[LOGICAL:EXPERT] /alpha > datasource host3 welcome
DataSource 'host3' is now OFFLINE
The datasource welcome command puts the datasource into the OFFLINE state. If the
dataservice policy mode is AUTOMATIC, the node will be placed into ONLINE mode
due to automatic recovery. When in MAINTENANCE or MANUAL mode,
the node must be manually set online.
The datasource welcome command may not always work if there has been a failure or topology change between the
moment it was shunned and welcomed back. Using the datasource recover command may be a better alternative to using
datasource welcome when bringing a datasource back online. The datasource recover command ensures
that the replicator, connector and operation of the datasource are correct within the current cluster configuration.