Hotcopy

This is a NuoDB Manager command. See NuoDB Manager.

Description

Obtain a copy of a running database. This copy contains the state of the storage manager or snapshot storage manager that it is run on as it was at approximately the time when the hot copy finished running. The database stored in the hot copy result is transactionally consistent. When performing full hot copy into an archive using destinationArchiveDirectory,you can use the result to start an SM or SSM, invoke the nuochk utility, or save as a backup. When performing full, incremental, or journal hot copy into a backup set using backupSetDirectory, you can restore the hot copy as an archive from the backup set using the nuochk utility; the restored archive can then be used to start an SM or SSM, or invoke the nuochk utility

Preview: Snapshot storage managers are preview features. The use of Hotcopy on Snapshot Storage Managers is also a preview feature.

NuoDB encourages you to use preview features in your development projects. The use of preview features in production is not supported.

Syntax

hotcopy database database_name
    [ snapshot number[-number ]]
    [ album number[-number] ]
    [ timeout timeout_value ]
    [ maxBlockedTime timeout_value ]
    [ backupSetDirectory backupset_path ]
    [ destinationArchiveDirectory archive_path ]
    [ destinationJournalDirectory journal_path ]
    [ destinationSnapshotDirectory snapshot_path ]
    [ host host_name ]
    [ type backup_type ]
    [ pid { sm_id | ssm_id } ]
    [ plan { @} filename]

Parameters

backupSetDirectory backupset_path

Store the hot copy into a backup set. Required if not using destinationArchiveDirectory. Required when using type incremental or type journal.

In this folder both full, incremental and hot copies will be stored, The user that NuoDB runs as must have read, write and execute permission on the parent directory. A type full hot copy will create a new backup set, and must be executed on an empty or non-existent backupSetDirectory. A type incremental and type journal hot copy must be executed on the most-recently created backup set directory (created by invoking full hot copy).

Note: In interactive mode, nuodbmgr prompts for parameters related to snapshots even when you specify that you are copying from a storage manager.

type backup_type

Required if using backupSetDirectory. the parameter value can be Full/Incremental/Journal and the determine the backup type
Full will run a full hot copy to a backup set contains archives, journals and footprints
Incremental will run a full hot copy to a backup set contains archives that changed from previous full backup, journaling and footprints
Journal will run a full hot copy to a backup set contains all the journals that changed from previous backup

Useful Properties

hotcopyTimeout

See NuoDB Manager Properties.

Interactive Example

Suppose you want to copy the current state of the test database, which is running on only the local host. There is only one storage manager running on the local host and you want the destination archive directory to be test_archive_hotcopy050515 in the default NuoDB database directory. Here is the command you would enter:

nuodb [domain] > hotcopy database test
Snapshot to copy, or firstSnapshot-lastSnapshot (optional): 
Album to copy, or firstAlbum-lastAlbum, 0 means current state (optional): 
Destination directory: test_archive_hotcopy050515
Destination journal directory (optional): 
Destination snapshot directory (optional): 
Storage Manager host (optional): 
Storage Manager process id (optional): 
Timeout (ms/s/m/h/d/w) (optional): 
Hot copy to /var/opt/nuodb/production-archives/test_archive_hotcopy050515 completed on myhost-jdoe-mac, pid 12345

The hot copy operation does the following:

Following is an example of invoking hotcopy on a snapshot storage manager:

nuodb [domain] > hotcopy database test
Snapshot to copy, or firstSnapshot-lastSnapshot (optional): 123456
Album to copy, or firstAlbum-lastAlbum, 0 means current state (optional): 
Destination directory: /hotcopyResults/test_archive
Destination journal directory (optional): 
Destination snapshot directory (optional): /hotcopyResults/test_archive/snapshots
Storage Manager host (optional): myHost
Storage Manager process id (optional): 98765
Timeout (ms/s/m/h/d/w) (optional): 
Hot copy to /hotcopyResults/test_archive completed on myhost-jdoe-mac, pid 98765

Scripting Example

The same command command can be executed with --command as follows:

$ nuodbmgr --broker host --password password \
    --command "hotcopy database test destinationArchiveDirectory test_archive_hotcopy050515"
$ nuodbmgr --broker host --password password \
    --command "hotcopy database test \
    host myHost \
    pid 98765 \
    snapshot 123456 \
    destinationArchiveDirectory /hotcopyResults/test_archive \
    destinationSnapshotDirectory /hotcopyResults/test_archive/snapshot"

Running HotCopy for Databases with Multiple Storage Groups

You must use the new plan argument to supply each SM on which hot copy will be run, and assume that this set of SMs covers the set of storage groups that you wish to back up, typically the entire database. Along with each SM, you will need to supply the location (on that SM) where the hot copy will be stored. You are responsible for managing these directories after the hot copy completes.

In addition to the current timeout (which specifies how long nuodbmgr should wait for the hot copy to finish, but doesn't cause the hot copy itself to be abandoned), a new timeout e.g. {{maxBlockedTime has been introduced. I}} If phase two of the hot copy (where pre-commit operations are blocked) takes longer than this set value, then the hot copy itself will be abandoned and fail.

Note: The REST interface does not fully support hot copy.

Hot Copy Plan Format

The format for a hot copy plan in JSON is as follows:


{
"defaultArchiveDir" : "dir", "defaultJournalDir" : "dir", "defaultSnapshotDir" : "dir",
“defaultBackupSetDir” : “dir”, "archives" : [
     {
        "host" : "hostname", "pid" : pidnum, "copyArchiveDir" : "dir", "copyJournalDir" : "dir", "copySnapshotDir" : "dir", “backupSetDir” : “dir”
     },
    ...
]
}

The rules governing this format are as follows:

  1. The default*Dir pairs are optional.
  2. If a default*Dir pair is given then its value will be used for every object in the archives list which doesn't provide the associated {{*Dir}}pair.
  3. If backupSetDir is provided in an object in the archives list, then do not provide copyArchiveDir, copyJournalDir, or copySnapshotDir.
  4. Every object in the archives list must contain a copyArchiveDir or a backupSetDir, unless a defaultArchiveDir or defaultBackupSetDir is provided.
  5. The host pair is required if there is more than one SM in the database, else it can be omitted.
  6. The pid pair is required if there is more than one SM defined on the host hostname, else it can be omitted.
  7. If an object in the archives list wants to "undefine" a Dir when a default*Dir value exists, the value can be set to null.

Plan Examples

Example 1:Backup

This is the simplest possible command and is equivalent to the hotcopy command using the destinationArchiveDirectory argument set to "/var/backup". This works if there's a single SM in the database.

{
     "archives" : [
       {
     "copyArchiveDir" : 
     "/var/backup" 
         }
         ]
}
Example 2: Default Values Definition

This plan defines default values to be used with all hosts then lists the hosts to be backed up. The assumption is that there is only one SM per host so the pid value is not needed.

{
     "defaultArchiveDir" : 
     "/var/backup",
     "defaultJournalDir" : 
     "/var/journal",
     "archives" : [{"host" : "host1"}, {"host" : "host2"}]
}
Example 3:Default Values Definition with PID and Multiple SMs

This plan is the same as the last one except host1 has multiple SMs and a PID was provided, and for host2 we didn't want to use a copy directory for the journal, and therefore the value is assigned to null to override the default.

{
     "defaultArchiveDir" : 
     "/var/backup",
     "defaultJournalDir" : 
     "/var/journal",
     "archives" : [{"host" : "host1"},"pid" : 1874 }, {"host" : "host2", "copyJournalDir" : null}]
}

Hot Copy Errors

For more information on any possible Hot Copy errors that you may encounter, see Examples of Hot Copy Errors.

Incremental Hotcopy

For more information, See Using Incremental Hot Copy or examples on Using Journal Hot Copy.