see on GitHub

Restore


Being able to restore data is, naturally, an inseparable part of backing it up.
You can restore backed up databases using the Studio, or client API methods.


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

    • Parameters:
    Parameter Value Functionality
    DatabaseName string Name for the new database.
    BackupLocation string Backup file local path.
    Backup source path has to be local for the restoration to continue.
    LastFileNameToRestore
    (Optional -
    omit for default)
    string Last backup file to restore.
    Default behavior: Restore all backup files in the folder.
    DataDirectory
    (Optional -
    omit for default)
    string 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 to disable ongoing tasks after restoring,
    false to enable tasks after restoring.
    Default: false (tasks DO run when backup is restored)

Make sure your server has permissions to read from BackupLocation and write to DataDirectory.

Verify that RavenDB has full access to the backup-files and database folders.

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 RestoreBackupOperation the configured RestoreBackupConfiguration.
    • Restore tha database by sending the task to the server.
  • 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

    • Use LastFileNameToRestore if you want to restore 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 be omitted.
  • DataDirectory
    Choose the location and name of the directory the database will be restored to.

    //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.

  • DisableOngoingTasks
    set DisableOngoingTasks to true to disable ongoing tasks after restoration.

    //Do or do not run ongoing tasks after restoration.
    //Default setting is FALSE, to allow tasks' execution when 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 cluster is to restore the backed-up database to a single server, and then expand the database group to additional nodes, allowing normal replication.


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.

  • Simultaneously restoring a logical-backup by multiple nodes, triggers each node to send change-vector updates to all other nodes.
  • Simultaneously restoring a snapshot does not initiate this behavior, because the databases kept by all nodes are considered identical.

  • 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).
    • Delete the databases from the cluster with HardDelete set 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 you create a backup of a database on one machine and restore it to another, you may be interested more in the database itself than in behaviors accompanying it like its ongoing tasks.

  • 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 backup is restored.
    restoreConfiguration.DisableOngoingTasks = true;