SAND CDBMS Administration Guide
Persistent Mode Operations (Time Travel)

Saving Changes to a Time Travel Database Instance

Using the SHUTDOWN...KEEP CHANGE Command in Persistent Mode

The core of Time Travel functionality is the ability to save multiple different versions of the database without replicating database files. Changes made to the current database Snapshot are saved by executing the SHUTDOWN...KEEP CHANGE command from an SQL session, thereby creating an Update File. This command can be executed even while the same database Snapshot or other Snapshots are in use by other nserv processes.

Syntax

The Update File (named database-name.Uxx, where xx is a hexadecimal number that increases incrementally with each update) is created in the same directory as the primary database file. For information about adding, modifying, and viewing data drives, consult the Database Configuration (nconfig) chapter of the SAND CDBMS Tools Reference Guide.

To save changes to the current database Snapshot:

1. Connect to the database instance as the user DBA, or another user with DBA privileges on the database.

2. Advise any other users of the database instance to disconnect. If the SHUTDOWN IMMEDIATE command option is used, all users are automatically disconnected when the server shuts down, destroying any unsaved work. If the SHUTDOWN DEFERRED option is specified, the command will be executed only when all sessions (including the current one) have been disconnected.

3. Issue the SHUTDOWN command:

SHUTDOWN IMMEDIATE KEEP CHANGE

-or-

SHUTDOWN DEFERRED KEEP CHANGE

Optionally, include the SET CURRENT option at the end of the command to have the new database Snapshot set as the current or default Snapshot (equivalent to executing nmerge -e snapshot-number):

SHUTDOWN IMMEDIATE KEEP CHANGE SET CURRENT

-or-

SHUTDOWN DEFERRED KEEP CHANGE SET CURRENT

If the new Snapshot is not explicitly set to current, the Snapshot that was current before the execution of the SHUTDOWN command stays current. The one exception to this rule is if the current Snapshot is the parent of the new Snapshot, in which case the new Snapshot automatically becomes current.

Note that, unlike Virtual Mode operation, the Time Travel KEEP CHANGE command option does not affect the actual physical data store, but results only in a virtual update, represented by the Update File. In order to change the real database, the nmerge command must be executed with the root database node ( 0 ) as the target, as described in the Merging Time Travel Database Snapshots section below; this will result in the deletion of all the Update Files that are dependent on the original database, in effect starting the tree structure anew.

If the KEEP CHANGE keyword is not included in the SHUTDOWN command, none of the changes made to the database will be retained when the nserv program is shut down.

Altering the Core Database

In Persistent Mode, the core database can only be changed by merging a Snapshot with the root node. Attempting to alter the database configuration record using nconfig, or compact the database with the ndbchk -p command, will produce an error message. Furthermore, all such attempts to change the core database will be disallowed as long as it has one or more Snapshots, regardless of the RunMode setting.

In order to change the database configuration record or compact the database, either of the following actions must first be performed:

• Remove the Time Travel tree file (database-name.tree) and Update Files (database-name.Unn) from the directory where the primary database file is located.
• Merge a Snapshot that has no "child" nodes with the root. This will cause all dependent Update Files to be deleted, since they would no longer be compatible with the new state of the database.

If a merge to the root node fails, the same operation must be repeated after the conditions that caused the failure have been corrected. The re-attempted merge operation will continue from where it was interrupted, using information saved to a file called database-name.rcv in the same directory as the primary database file. This .rcv file must not be manually deleted or moved. When the merge operation has completed successfully, the .rcv file will be removed automatically.

The following are the main error messages related to merge recovery:

No disk space available on drive: x
The required amount of disk space could not be allocated while performing a merge operation. Free up a sufficient amount of disk space on the specified drive, then re-attempt the merge operation.

Unable to open database
The core database file(s) could not be opened during a merge operation. Ensure that you possess the appropriate access permissions on the database, and that no other process has the database locked.

Unable to read configuration data from RECOVERY-file: error: x
Unable to read recovery info from RECOVERY-file: error: x
The nmerge recovery file (database-name.rcv) could not be read. Ensure that you possess the appropriate access permissions on the recovery file, and that no other process has the recovery file locked.

Unable to restart from RECOVERY-file: bad snapshot number: RCV: x, SNAPSHOT: y
This message is returned after a merge-to-root operation has failed, and a subsequent merge operation specifies a different Snapshot to merge with the root node. The exact same merge operation that failed previously must be performed in order to complete the interrupted merge.

Unable to write recovery info to RECOVERY-file: error: x
Unable to write configuration data to RECOVERY-file: error: x
The nmerge recovery file (database-name.rcv) could not be written to during a merge operation. Ensure that you possess the appropriate access permissions on the target directory and recovery file, and that no other process has the recovery file locked.

Snapshot x has a parent marked for deletion
This message is returned after a merge-to-root operation has failed, and a subsequent merge operation specifies different merge points on the same branch of the version tree where the merge failed. The original merge-to-root operation must be completed before any other merges can be performed on that branch