SAND CDBMS Administration Guide
Persistent Mode Operations (Time Travel)


Previous Topic:
Starting a Time Travel Database Instance
Chapter Index
Next Topic:
Time Travel File Types


Merging Time Travel Database Snapshots

The SAND CDBMS Snapshot Administration Utility (nmerge)

The SAND CDBMS Snapshot Administration utility (nmerge) allows a user to merge Time Travel Snapshots (database versions), delete Snapshots, display information about the Snapshots, and perform other administrative tasks.

Over time, the Time Travel version tree can get large and unwieldy, as many Snapshots are created and branched. One way to manage the version tree is to delete unused branches. This is accomplished by selecting a Snapshot as the root of the branch that will be "pruned" from the version tree. When the operation is carried out, the chosen Snapshot and all descendent Snapshots (if any) are removed. Note that a Snapshot being used by an nserv process cannot be deleted; the database instance must be shut down first.

Another way to manage the version tree is to merge Snapshots together. Merging allows incremental changes to be consolidated in a single node, or even saved to the physical database itself. When performing a merge, one Snapshot is selected as the source of the merge, while another Snapshot is chosen as the target. The target Snapshot must be in a higher position on the same branch of the Time Travel version tree; the source and target cannot be on adjacent branches. When the merge is complete, the source Snapshot will replace the target Snapshot, as well as all intervening Snapshots, on the version tree. Snapshots that descend from the source Snapshot will remain in the version tree, but all other "child" branches from the target Snapshot will be removed, since they would no longer apply to the new state of the parent node.

If an Update File was relocated to another directory using the nmerge -l command, the Update File resulting from a merge operation will be saved in that same directory if, and only if, the relocated Update File represents the source Snapshot.

If a particular Snapshot is in use by an nserv process, that Snapshot cannot be involved in an immediate merge operation: it cannot be the source or target of the merge, and it cannot be located between the source and target Snapshots on the version tree. To perform such a merge, either the Snapshot must first be shut down, or else a pending merge must be specified. In the latter case, the operation will be flagged as "pending", and the actual merge will take place only when the relevant database versions are shut down.

A merge operation does not affect the real physical data store unless a Snapshot is merged with the Root database (node 0). Merging any node with the Root will result in the deletion of all Update Files dependent on the original database. The new version tree will consist only of the root node.

Before running nmerge, ensure that the appropriate DATABASE section in the nucleus.ini file contains a RunMode=persistent entry, otherwise nmerge will not function.

Be careful when making changes through nmerge, as there are no confirmation prompts and an nmerge operation cannot be undone. Also note that the Update Files associated with removed Snapshots are physically deleted when merging or deleting Snapshots.

The nmerge command uses the following syntax:

nmerge option-flag [ option-flag-arguments ] database-name

Flags and Arguments

The nmerge invocation requires one of the following flag parameters:

The -h flag displays a help screen that describes nmerge syntax and usage. This flag takes no arguments. The database-name parameter is not required if the -h flag is used.

The -c flag creates a new
database-name.tree file without starting a database instance. The tree structure of the resulting .tree file contains only the root node.

-d snapshot-number
The -d flag instructs nmerge to remove the specified Snapshot and all child Snapshots from the database version tree, and delete the associated Update Files. That is, the entire branch for which the specified Snapshot is the root node is removed from the version tree. The root database (Snapshot 0) cannot be deleted using this flag.

-e snapshot-number
The -e flag sets the specified Snapshot as the current (default) Snapshot. This is the Snapshot that is started when nserv is invoked without specifying a Snapshot number.

-g file-name
The -g flag translates the database tree structure information in a database-name.tree file into a readable format, and writes this information to the specified text file. The -g flag can be used to back up a .tree file, since the -w flag is used to recreate a .tree file from the text file created with -g.

-l snapshot-number new-location
The -l flag is used to relocate an Update File. The flag arguments are Snapshot number (which identifies the Update File that will be moved), and the directory path where the Update File will be moved. If the path contains any spaces, surround the path with quotation marks (' ').

-m { c | <source-snapshot-number> } [ { <target-snapshot-number> | -n } ]
The -m flag specifies a merge between multiple Time Travel database versions. This flag can take the following arguments:

<source-snapshot-number> <target-snapshot-number>
A Snapshot (source-snapshot-number) is merged with another Snapshot higher up on the same branch of the database version tree (target-snapshot-number). The order of the arguments is important: source-snapshot-number must be a "descendent" (direct or indirect child) of target-snapshot-number.

<source-snapshot-number> -n
Instead of specifying a target Snapshot number, '-n' can be used to select the Snapshot n nodes above the source Snapshot in the database version tree (where n is a positive integer).

c { <target-snapshot-number> | -n }
Instead of specifying a source Snapshot number, the current (default) Snapshot can be referenced by using 'c'.

When 'c' is specified without a target Snapshot, the current (default) Snapshot is merged with Snapshot 0 (the root database). Note that all Update Files are deleted in this situation, as they are no longer consistent with the new version of the database.

The merge operation does not affect the real physical data store unless a node is merged with the root database (snapshot-number=0). Merging any node with the root database will result in the deletion of all Update Files dependent on the original database.

-p { c | <source-snapshot-number> } [ { <target-snapshot-number> | -n } ]
The -p flag specifies a pending merge between two Time Travel database versions, using the same arguments as -m above. The -p 'c' option differs from the -m 'c' option, however:

When 'c' is specified without a target Snapshot, a pending merge of the current (default) Snapshot with Snapshot 1 is scheduled.

The flag is useful when the Time Travel option is being used with Octopus in a 24x7 operating environment: it allows for the specification of a merge operation while an Update File in the affected branch is still in use. The new merged Snapshot will automatically be included in the branch the next time a database instance is started. This minimizes database "downtime."

The -r flag refreshes the sequence of Snapshots in the database version tree, removing any gaps between Snapshot numbers. Snapshots are numbered in sequence according to the order of their creation. These numbers are retained even after other nodes have been merged or deleted. After many merges or deletes have been executed on a particular database tree structure, the numbering of the nodes (Update Files) may become difficult to read. In this case, the -r flag can be used to re-establish the sequence.

-s { c | { <source-snapshot-number> { <target-snapshot-number> | -n } }
The -s flag estimates the size of the Update File (or the physical database, in the case of the 'c' option) that would result from the specified merge. Note that this command does not actually perform the merge. Refer to the -m flag above for a description of the arguments.

-t snapshot-number "text-label"
The -t flag attaches a text label to the specified Snapshot. The label can be viewed subsequently using nmerge -v u, or through the Time Travel Manager (Windows only). The text label must be enclosed by double quotation marks (") and cannot exceed 255 characters in length. If double quotation marks are part of the text label, it must be "escaped" by preceding it with a backslash, as in the following manner: \".

The -u flag is used to attempt to recover the Time Travel database tree file (database-name.tree) if it is accidentally deleted or becomes unusable. This file contains required information regarding the structure of the database version tree. If it is lost or damaged, existing Snapshots of the database cannot be opened.

If a tree file already exists, rename or move it prior to executing nmerge -u, otherwise the operation will fail. Following a successful tree file recovery, node 0 (the root database) becomes the current Snapshot. Use the -e flag to select another Snapshot as the default.

The -u flag can only recover a tree file if all of the Update Files for the database are located in the same directory.

-v [ snapshot-number | c | f | l | m | p | q{0|1|2} | s | t | u ]
The -v flag is used to display diagnostic database tree structure information. The following arguments, which can be used in any combination, determine the type of information displayed:

snapshot-number Tree structure information starting from the specified Snapshot number
c Current Snapshot
f Update Files marked for deletion
l Path location of the database file relative to the database version tree file
m Temporary file(s)
p Checkpoint numbers. The first is the checkpoint from when the Snapshot was started; the second is the checkpoint to which the latest changes were committed.
q{0|1|2} Displayed data is sorted by Snapshot number (q0), parent node (q1), or last modification time (q2)
s Size (in MB) of the Update File for the current or specified Snapshot
t Last modification time of the current or specified Snapshot
u User information

If no arguments are specified for -v, then the following are applied by default: t, s and l.

-w file-name [ 0 | 1 ]
The -w flag causes the existing database-name.tree file to be updated with the tree structure information recorded in a text file via the -g flag. This can be useful for restoring a .tree file that is corrupted. If used for this purpose, however, it is important that the tree structure information in the text file corresponds to the current tree structure, otherwise the resulting .tree file will be inaccurate. That is, Snapshots should not have been merged, deleted, or renumbered since the backup text file was created.

If the actual tree structure has changed since the text tree file was created, the backup information can still be used to recover the .tree file, provided the contents of the text file are edited properly. In this situation, it is highly recommended that a SAND support representative be contacted for assistance.

There are two optional flag values for -w: 0 and 1. Option 0 is used to update existing information in the .tree file. If the actual tree structure has not been altered, or if the text tree file has been edited in a way that does not affect the tree structure (for example, the current Snapshot number is changed), option 0 should be used. This option is the default, so "-w file-name 0" and "-w file-name" are equivalent.

Option 1 is used to overwrite completely the information in the .tree file. If the text tree file is edited in a way that alters the tree structure (for example, the number of Nodes is changed), option 1 should be used (that is, "-w file-name 1").

The -w flag requires an existing .tree file on which to operate. If the original .tree file was moved or deleted, use the -c flag to create a basic .tree file for the database.

Exercise caution when using the -w flag. If applied improperly, it could result in an unusable .tree file.

Sample nmerge Commands:

nmerge -v 3 q2 DB1

Displays the database version tree structure information, based on the original database named DB1, beginning with Snapshot 3, sorted by last modification time

nmerge -m 6 2 DB1

Merges Snapshot 6 with Snapshot 2 in the tree structure based on the database named DB1
(Note: Snapshot 2 is higher than Snapshot 6 on the same branch of the tree structure)

nmerge -g db1.txt DB1 Writes the tree structure information for the database named DB1 to an ASCII text file called db1.txt


Previous Topic:
Starting a Time Travel Database Instance
Chapter Index
Next Topic:
Time Travel File Types