@SnapshotRestore

Documentation

VoltDB Home » Documentation » Using VoltDB

@SnapshotRestore

@SnapshotRestore — Restores a database from disk using a native format snapshot.

Synopsis

@SnapshotRestore String directory-path, String unique-ID

Description

The @SnapshotRestore system procedure restores a previously saved database from disk to memory. The snapshot must be in native format. (You cannot restore a CSV format snapshot using @SnapshotRestore.) The restore request is propagated to all nodes of the cluster, so a single call to @SnashotRestore will restore the entire database cluster.

The first parameter, directory-path, specifies where VoltDB looks for the snapshot files.

The second parameter, unique-ID, is a unique identifier that is used as a filename prefix to distinguish between multiple snapshots.

You can perform only one restore operation on a running VoltDB database. Subsequent attempts to call @SnapshotRestore result in an error. Note that this limitation applies to both manual and automated restores. Since command logging often includes snapshots, you should never perform a manual @SnapshotRestore after recovering a database using command logs.

See Chapter 9, Saving & Restoring a VoltDB Database for more information about saving and restoring VoltDB databases.

Return Values

Returns one VoltTable with a row for every table restored at each execution site.

NameDatatypeDescription
HOST_IDINTEGERNumeric ID for the host node.
HOSTNAMESTRINGServer name of the host node.
SITE_IDINTEGERNumeric ID of the execution site on the host node.
TABLESTRINGThe name of the table being restored.
PARTITION_IDINTEGERThe numeric ID for the logical partition that this site represents. When using a K value greater than zero, there are multiple copies of each logical partition.
RESULTSTRINGString value indicating the success ("SUCCESS") or failure ("FAILURE") of the request.
ERR_MSGSTRINGIf the result is FAILURE, this column contains a message explaining the cause of the failure.

Examples

The following example uses @SnapshotRestore to restore previously saved database content from the path /tmp/voltdb/backup/ using the unique identifier flight.

$ sqlcmd
1> exec @SnapshotRestore '/tmp/voltdb/backup/', 'flight';

Alternately, you can use the voltadmin restore command to perform the same function:

$ voltadmin restore /tmp/voltdb/backup/ flight

Since there are a number of situations that impact what data is restored, it is a good idea to review the return values to see what tables and partitions were affected. In the following program example, the contents of the VoltTable array is written to standard output so the operator can confirm that the restore completed as expected.

VoltTable[] results = null;

try {
     results = client.callProcedure("@SnapshotRestore",
                                    "/tmp/voltdb/backup/",
                                    "flight").getResults();
}
catch (Exception e) {
    e.printStackTrace();
}

for (int t=0; t<results.length; t++) {
    VoltTable table = results[t];
    for (int r=0;r<table.getRowCount();r++) {
        VoltTableRow row = table.fetchRow(r);
        System.out.printf("Node %d Site %d restoring " +
              "table %s partition %d.\n",
              row.getLong("HOST_ID"), row.getLong("SITE_ID"),
              row.getString("TABLE"),row.getLong("PARTITION"));
     }
}
>