Skip to main content

Restore

Restoring a Database: Configuration and Execution​

To restore a database, set a RestoreBackupConfiguration instance and pass it to RestoreBackupOperation for execution.

RestoreBackupOperation​

public RestoreBackupOperation(RestoreBackupConfiguration restoreConfiguration)

RestoreBackupConfiguration​

public class RestoreBackupConfiguration
{
  public string DatabaseName { get; set; }
  public string BackupLocation { get; set; }
  public string LastFileNameToRestore { get; set; }
  public string DataDirectory { get; set; }
  public string EncryptionKey { get; set; }
  public bool DisableOngoingTasks { get; set; }
  public bool SkipIndexes { get; set; }
}

  • Parameters:

    ParameterValueFunctionality
    DatabaseNamestringName for the new database.
    BackupLocationstringLocal path of the backup file to be restored.
    Path must be local for the restoration to continue.
    LastFileNameToRestore
    (Optional -
    omit for default)    		stringLast incremental backup file to restore.
    Default behavior: Restore all backup files in the folder.
    DataDirectory
    (Optional -
    omit for default)    		stringThe new database data directory.
    Default folder: Under the "Databases" folder, in a folder that carries the restored database's name.
    EncryptionKey
    (Optional -
    omit for default)    		stringA key for an encrypted database.
    Default behavior: Try to restore as if DB is unencrypted.
    DisableOngoingTasks
    (Optional -
    omit for default)    		booleantrue - disable ongoing tasks when Restore is complete.
    false - enable ongoing tasks when Restore is complete.
    Default: false (Ongoing tasks will run when Restore is complete).
    SkipIndexes
    (Optional -
    omit for default)    		booleantrue to disable indexes import,
    false to enable indexes import.
    Default: false restore all indexes.
    • Verify that RavenDB has full access to the backup-files and database folders.
    • Make sure your server has permissions to read from BackupLocation and write to DataDirectory.

Optional Settings​

LastFileNameToRestore​

Restore incremental backup files up to (including) the selected file, and stop restoring there.

  • E.g. -
    • These are the files in your backup folder:
      2018-12-26-09-00.ravendb-full-backup
      2018-12-26-12-00.ravendb-incremental-backup
      2018-12-26-15-00.ravendb-incremental-backup
      2018-12-26-18-00.ravendb-incremental-backup
    • Feed LastFileNameToRestore with the 2018-12-26-12-00 incremental-backup file name:
//Last incremental backup file to restore from
restoreConfiguration.LastFileNameToRestore = @"2018-12-26-12-00.ravendb-incremental-backup";
  • The full-backup and 12:00 incremental-backup files will be restored.
    The 15:00 and 18:00 files will not be restored.

DataDirectory​

Specify the directory into which the database will be restored.

// Restore to the specified directory path
var dataPath = @"C:\Users\RavenDB\backups\2018-12-26-16-17.ravendb-Products-A-backup\restoredDatabaseLocation";
restoreConfiguration.DataDirectory = dataPath;

EncryptionKey​

This is where you need to provide your encryption key if your backup is encrypted.

restoreConfiguration.EncryptionKey = "your_encryption_key";

DisableOngoingTasks​

set DisableOngoingTasks to true to disable the execution of ongoing tasks after restoration.
See Recommended Precautions.

// Do or do not run ongoing tasks after restoration.
// Default setting is FALSE, to allow tasks' execution when the backup is restored.
restoreConfiguration.DisableOngoingTasks = true;

Restore Database to a Single Node​

  • Configuration

    • Set DatabaseName with the new database name.
    • Set BackupLocation with a local path for the backup files.

  • Execution

    • Pass the configured RestoreBackupConfiguration to RestoreBackupOperation.
    • Send the restore-backup operation to the server to start the restoration execution.

  • Code Sample:

var restoreConfiguration = new RestoreBackupConfiguration();

// New database name
restoreConfiguration.DatabaseName = "newProductsDatabase";

// Local path with a backup file
var backupPath = @"C:\Users\RavenDB\backups\2018-12-26-16-17.ravendb-Products-A-backup";
restoreConfiguration.BackupLocation = backupPath;

var restoreBackupTask = new RestoreBackupOperation(restoreConfiguration);
docStore.Maintenance.Server.Send(restoreBackupTask);

Restore Database to Multiple Nodes​

Restore Database to a Single Node & Replicate it to Other Nodes​

The common approach to restoring a database that should reside on multiple nodes, is to restore the backed-up database to a single server and then expand the database group to additional nodes, allowing normal replication.

  • Verify relevant nodes exist in your cluster. Add nodes as needed.
  • Manage the database-group topology.
    Add a node to the database-group using the Studio or from your code, to replicate the database to the other nodes.

Restore Database to Multiple Nodes Simultaneously​

You can create the cluster in advance, and restore the database to multiple nodes simultaneously.

This procedure is advisable only when restoring a Snapshot.

  • When a logical-backup is restored, each document receives a new change-vector according to the node it resides on.
    When the database instances synchronize, this change-vector will be updated and be composed of all database nodes tags.

  • When a snapshot is restored, documents are not assigned a new change-vector because the databases kept by all nodes are considered identical.
    Each document retains the original change-vector it had during backup.
    When the database instances synchronize, documents' change-vectors do not change.

  • On the first node, restore the database using its original name.
  • On other nodes, restore the database using different names.
  • Wait for the restoration to complete on all nodes.
  • Soft-delete the additional databases (those with altered names) from the cluster.
    Soft-delete the databases by setting HardDelete to false, to retain the data files on disk.
  • Rename the database folder on all nodes to the original database name.
  • Expand the database group to all relevant nodes.

When restoring a backed-up database, you may be interested only in the restored data and not in any ongoing tasks that may have existed during backup.

  • E.g., an ETL ongoing task from a production cluster may have unwanted results in a testing environment.

In such cases, disable ongoing tasks using the DisableOngoingTasks flag.

  • Code Sample:
// Do or do not run ongoing tasks after restoration.
// Default setting is FALSE, to allow tasks' execution when the backup is restored.
restoreConfiguration.DisableOngoingTasks = true;

In this article