9.27. The tprovision Script

Version Support: 7.0.0

tprovision was previously known as tungsten_provision_slave and was renamed in v7.0.0

For instructions for releases older than this, please refer to the documentation here

The tprovision script allows you to easily provision, or reprovision, a database server using information from a remote host.

tprovision [ -r, --check-repl-channel  ] [ -c, --create-master  ] [ --flush-after-sleep  ] [ --help, -h ] [ --method, -m ] [ --port, -p  ] [ --seed  ] [ --source, -s ] [ --threads, -t  ]

Where:

Table 9.64. tprovision Command-line Options

OptionDescription
-r, --check-repl-channelCheck that the number of replication channels when using parallel apply is the same for both source and target. On by default, set to 0 to disable check.
-c, --create-masterUse to flag to the script that the node being provisioned needs to be a Primary. Valid for Composite Active/Active only. Forces the provision of a failed Primary and will reset services.
--flush-after-sleepHow long we wait (in seconds) to get a full database write lock before final rsync pass. Valid and required only for rsync method
--help, -hShow help text
--method, -mBackup method to use. Valid methods are mysqldump, xtrabackup, rsync (v7.0.2+), and mysqlclone (v7.1.0+).
--port, -pPort to use to connect to MySQL when using mysqldump, or ssh port when using xtrabackup.
--seedJust do a single non-locking pass when using rsync.
--source, -sServer to use as a source for the backup
--threads, -tNumber of parallel threads to use for xtrabackup. Increasing this number on large databases may improve backup speeds. If not supplied, default will be based on the default for the revision of xtrabackup in use.

Important

It is recommend to run this script in a utility such as screen in case the terminal gets disconnected.

For both mysqldump and xtrabackup methods, the script will perform a streaming backup from the source node to the target node.

The script will automatically put all replication services offline prior to beginning. If the services were online, the script will put them back online following a successful completion. All THL logs will be cleared prior to going online. The replicator will start replication from the position reflected on the source host.

Provisioning will fail from a Replica that is stopped, or if the Replica is not in the ONLINE state.

Using xtrabackup

The script will run validation prior to starting to make sure the needed scripts are available. The provision process will run Xtrabackup on the source server and stream the contents to the server you are provisioning. After taking the backup, the script will prepare the directory and restart the MySQL server

Using mysqldump

The script will run mysqldump by default.

Using rsync

Note

Provisioning using rsync was introduced in v7.0.2

The script will copy the source database to the target using rsync, using two passes. The first pass will simply copy the database live. This will produce an inconsistent database on the target but will have seeded the target database.

Pass 2 will quiesce the source database and do a final rsync. Because pass 1 had already seeded the data, pass 2 should be quick, minimizing the downtime on the source database.

Note that quiescing the database can take some time while we wait for in process transactions to complete. By default, we will wait 5 seconds when the source is a replica. When provisioning from a primary, there is no default and you must specify a time using the --sleep-after-flush option, in seconds, to wait. If the write lock cannot be obtained during this time, the script will abort before performing pass 2.

To only run the first pass, use the --seed option. This is useful to seed the target in advance and can be done multiple times to get the target seeded ahead of time to reduce downtime during a maintenance window.

Using rsync is not recommended when the source database is a primary, due to the database being quiesced and thus potentially causing downtime. The script normally will not allow you to do this, however you can override this check with the option --i-am-sure and force a provision from a primary database.

Using mysqlclone

Note

Provisioning using mysqlclone was introduced in v7.1.0, and requires MySQL 8.0.17+

Beginning with mysql version 8.0.17, you can clone a database using mysqlclone. This requires the mysql_clone.so plugin on both the donor (source) and target. The script will attempt to install it if it is not installed already.

Note

Note that mysqlclone ONLY supports InnoDB table types.

Compatibility

The script only works with MySQL at this time.

Logging

The script will log output to the /opt/continuent/service_logs directory.

Example

To reprovision the Replica db3 from another Replica, db2. Using xtrabackup

db3-shell> tprovision --source db2 --method xtrabackup

To reprovision the Replica db3 from another Replica, db2. Using the default, mysqldump

db3-shell> tprovision --source db2

To reprovision the PRimary db1 from the Primary, db4, in the remote cluster. Using Xtrabackup. This is only applicable to Composite Active/Active topologies

db1-shell> tprovision --source db4 -c --method xtrabackup

To reprovision the replica db3 from another replica, db2, using rsync and only seeding the database on db3

db3-shell> tprovision --source db2 --method rsync --seed

After seeding (above), run the rsync again. The amount of time the database is locked now should be much less since we've already seeded the database changes. We will wait 10 seconds to acquire the lock:

db3-shell> tprovision --source db2 --method rsync --sleep-after-flush 10

Reprovision db3 from db2 using mysqlclone (MySQL 8.0.17+)

db3-shell> tprovision --source db2 --method mysqlclone