Restore



Restoring a Database: Configuration and Execution

To restore your database, configure 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:

    Parameter Value Functionality
    DatabaseName string Name for the new database.
    BackupLocation string Local path of the backup file to be restored.
    Path must be local for the restoration to continue.
    LastFileNameToRestore
    (Optional -
    omit for default)
    string Last incremental backup file to restore.
    Default behavior: Restore all backup files in the folder.
    DataDirectory
    (Optional -
    omit for default)
    string The 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)
    string A key for an encrypted database.
    Default behavior: Try to restore as if DB is unencrypted.
    DisableOngoingTasks
    (Optional -
    omit for default)
    boolean true - 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)
    boolean true 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.

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

Optional Settings:

  • LastFileNameToRestore
    Restore incremental backup files until a certain file is reached, and stop there.
    For example -

    • 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 a pre-chosen folder
    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 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;