@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

@SnapshotRestore String json-encoded-options

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 @SnapshotRestore will restore the entire database cluster.

If the database is empty — that is, there is no data or schema defined in the database — the restore operation restores the schema and the requested data. If a schema is already defined, the restore operation restores data only for those tables defined in the current schema.

There are two forms of the @SnapshotRestroe procedure, as described below. See Chapter 13, Saving & Restoring a VoltDB Database for more information about saving and restoring VoltDB databases.

Individual Arguments

When you specify the arguments as individual parameters, you must specify two arguments:

  1. The directory path where the snapshot files are stored

  2. An identifier that uniquely identifies the snapshot

JSON-Encoded Arguments

When you specify the arguments as a JSON-encoded string, you can specify not only what snapshot to use, but what data to restore from that snapshot. Table G.1, “@SnapshotRestoreOptions” describes the possible options when restoring a snapshot using JSON-encoded arguments.

Table G.1. @SnapshotRestoreOptions

OptionDescription
pathSpecifies the path where the snapshot files are stored.
nonceSpecifies the unique identifier for the snapshot.
skiptables

Specifies tables to leave out when restoring the snapshot. Use of tables or skiptables allows you to restore part of a snapshot. Specify the list of tables as a JSON array. For example, the following JSON argument excludes the Areacode and Country tables from the restore operation:

"skiptables":["areacode","country"]
tables

Specifies tables to include when restoring the snapshot. Use of tables or skiptables allows you to restore part of a snapshot. Specify the list of tables as a JSON array. For example, the following JSON argument includes only the Employee and Company tables in the restore operation:

"tables":["employee","company"]

For example, the JSON-encoded arguments to restore the tables Employee and Company from the "mydb" snapshot in the /tmp directory is the following:

{path:"/tmp",nonce:"mydb",tables:["employee","company"]}

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"));
     }
}