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. You can use it to open a database, start an SM or SSM, invoke the the nuochk utility, or save as a backup.

Preview: Snapshot storage managers and the ability to restore data to a snapshot are preview features. The use of Hotcopy on Snapshot Storage Managers is also a preview feature by virtue of the fact that they themselves are a preview feature.

Preview: NuoDB encourages you to use preview features in your development projects. However, 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 ]
    [ destinationArchiveDirectory archive_path ]
    [ destinationJournalDirectory journal_path ]
    [ destinationSnapshotDirectory snapshot_path ]
    [ host host_name
    [ pid { sm_id | ssm_id } ]
    [ plan { @} filename]

Parameters

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

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 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",
     "archives" : [
         {
             "host" : "hostname",
             "pid" : pidnum,
             "copyArchiveDir" : "dir",
             "copyJournalDir" : "dir",
             "copySnapshotDir" : "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 {{copy*Dir}}pair.
  3. Every object in the archives list must contain a copyArchiveDir unless a defaultArchiveDir is provided.
  4. The host pair is required if there is more than one SM in the database, else it can be omitted.
  5. The pid pair is required if there is more than one SM defined on the host hostname, else it can be omitted.
  6. If an object in the archives list wants to "undefine" copyJournalDir or copySnapshotDir 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.