Hot Copy Command Formats

Several commands are provided:

For more information on NuoDB Command and other command line tools, see Command Line Tools.

They can also be issued via the nuoadmin REST API (AP port 8888), see hotCopyDatabase and getHotCopyStatus. This is useful for scripting or writing your own utilties.

Initiating a Hot Copy

To create a copy of the current state of a running database, invoke the nuocmd hotcopy database command. The full syntax can be found here.

Things to note:

  • A simple hot copy backup (specify --type simple) will produce an archive at the backup location. All other hot copy types produce a backup set at the backup location.

  • If --default-backup-dir is specified all the archives in the database will be backed up. In practice this is probably not what you want.

  • For any backup set, the first incremental hot copy operation can only be performed once the full hot copy creating the backup set has completed successfully.

    • A journal hot copy can commence before the full hot copy has finished provided the backup set has been initialized (the first step performed by a full hot copy is to initialize the backup set with necessary metadata).

  • The result of the full hot copy operation is a new backup set directory into which incremental hot copy and journal hot copy operations can store their backup data.

  • The control folder located in the backup set directory must be accessible by the hot copy command to perform an incremental or journal backup. However the entire full backup image does not need to be accessible by hot copy command for the incremental hot copy command to be executed.

  • As part of the hot copy command, you must manually specify the id(s) of the archive(s) of the Storage Manager(s) to back up. See also caution warning for backup-dirs below.

Parameters to note:

Option Description

db-name

Required. Specify the name of the database on which to perform the hot copy.

type

Required. The type of hot copy to perform. Must be either simple,full,incremental or journal.

backup-dirs

Required unless --default-backup-dir is supplied.

  • May be specified as well as --default-backup-dir.

  • A space separated list of '<archive ID> <backup-path>' pairs specifying the backup location for each archive.

Unless backing up storage groups, only specify one archive per hot copy command to avoid the overhead of a coordinated hot copy.

default-backup-dir

Required, unless --backup-dirs are supplied. Backup any archives that do not have a backup location specified in --backup-dirs to this location.

  • Causes all archives to be backed up, this is typically not what you want.

  • The path specified must be valid for every SM host.

  • If it is a network mounted path, also specify --shared. Never use this with a simple hot copy.

process-filter

Optional. If --default-backup-dir is specified, restrict the SMs that are actually backed up using a load-balancing (LBQuery) expression. The SM processes to be used for hot copy backup should be started with an identifying label see example below.

shared

Optional. If --default-backup-dir is specified, this signifies that the backup location is on shared storage exposed to multiple SMs.

  • The directory specified by --default-backup-dir must exist.

  • Each archive will backup to a subdirectory inside that directory corresponding to the archive ID of the archive.

max-rate

Optional. If specified, the maximum I/O rate in MB/second (per SM.)

  • If the hot copy tries to go faster than this, it will be throttled to slow it down. This can minimize interference of hot copy with other I/O.

timeout

Optional. The number of seconds to wait for hot copy to complete before returning.

  • If a value is not provided, the request is issued asynchronously and immediately returns.

  • Once the timout expires, the command returns even if the hot copy has not finished

  • In either case, the status of the hot copy can be checked using one of the commands listed below.

Using the Process Filter Option

This is typically used when you have storage groups and allows you to specify which subset of SMs to use in a coordinated hot copy.

The SMs to be used need identifying with a label, for example:

nuocmd start process ... --type SM --labels role hotcopy

Here is the corresponding hot copy command:

nuocmd hotcopy database --db-name testdb --type full --default-backup-dir /volume/backups/test-db-2022-04-18 --process-filter "label(role hotcopy)"

Getting Information About a Hot Copy

The output from a hot copy command specifies a unique hot copy task id and a coordinator start-id (the ID of the SM coordinating the backup, important when multiple storage groups and their archives are being backed up).

For example, running:

nuocmd hotcopy database --db-name testdb --type incremental --backup-dirs 0 /mnt/backups/testdb

Generates this output:

HotCopyResponse(coordinator_start_id=2, id=f52ae347-e83f-44c3-ad1c-a8a30d7e47b4)

Make a note of the coordinator_start_id and the id.

Even when only one archive is specified to the hot copy command (as here), its SM is still registered as the "coordinator".

When multiple archives are specified, one of their SMs becomes the coordinator to ensure all backups are transactionally consistent. Multi-archive backup is only required when using storage groups (see coordinated hot copy).

nuocmd get hotcopy-info

Get details of hot copy command(s) for a given SM using its start-id (see above for details of the coordinator-start-id):

nuocmd get hotcopy-info --coordinator-start-id 2

Alternatively, get details of all hot copy command(s) for a given database:

nuocmd get hotcopy-info --db-name testdb

It is possible that you might have multiple hot copy jobs running at the same time.

  • You might be backing up more than one archive at a time, to ensure redundancy (in case one hot copy fails).

  • A journal hot copy can run at the same time as a full or incremental hot copy.

You can restrict the output to view just the longest running jobs with --running-for <duration>.

  • The default unit for duration is seconds

  • Use 'd', 'h' or 'm' to specify a duration in days, hours or minutes respectively - such as 2h for 2 hours.

The full syntax can be found here.

nuocmd show hotcopy-info

Shows all the hot copy information for a given database using a more human readable format:

nuocmd show hotcopy-info --db-name testdb

Show has two extra options. You can optionally override how the SM process details and hot copy status details are formatted.

The full syntax can be found here.

nuocmd get hotcopy-status

Requires use of both the coordinator-start-id and the id to uniquely identify a specific hot copy task (see above for where to get them).

nuocmd get hotcopy-status --coordinator-start-id 2 --hotcopy-id f52ae347-e83f-44c3-ad1c-a8a30d7e47b4

Whilst running, the output is like this:

HotCopyResponse(begin_timestamp=2019-06-18 10:18:37, coordinator_start_id=2, id=832c7a5f-11c2-44ed-8802-00237c347c4e, message=Stage1: Copy journal, status=running)

Once finished, you will see:

HotCopyResponse(begin_timestamp=2022-04-18 22:53:32, coordinator_start_id=2, end_timestamp=2022-04-18 22:53:33, id= 832c7a5f-11c2-44ed-8802-00237c347c4e, message=Hot copy successfully completed, status=completed)

The full syntax can be found here.

Cancelling a Hot Copy

To cancel a running hot copy, run

nuocmd cancel hotcopy --coordinator-start-id 2 --hotcopy-id f52ae347-e83f-44c3-ad1c-a8a30d7e47b4

See Getting Information About a Hot Copy for where to find coordinator-start-id` and hotcopy-id.

This request runs asynchronously so nuocmd returns immediately. You can make it wait by specifying a timeout.

The full syntax can be found here.