Administration: Backup and Restore

Backups can be performed while a database is online and accepts requests (including writes). There are two ways to perform a backup:

• Using your existing enterprise backup solution. RavenDB supports VSS backups, which is how most backup solutions on Windows work, for databases running on Esent storage. You can do that by configuring your backup solution to take backups of the Raven's data directory.
• RavenDB's own backup & restore system which supports databases running on both types of storages (Voron and Esent). You can ask a RavenDB server to perform a complete backup of its data to a specified directory at any time. During the backup procedure, the database remains online and can respond to read and write requests. However, a database remains at this state only in the beginning of the backup.

Backward compatibility

RavenDB relies on the OS services to manage data storage and backup. Those services are forward compatible (if you backup on Windows XP you can restore on Windows 7) but not backward compatible (if you backup on Windows 2008 you cannot restore on Windows 2003).

If you want to move a database content between different Operating System versions, you should use the Import / Export function, performed by Raven.Smuggler.

Initiating a backup

When running in an embedded mode, all you need is to call the method DocumentDatabase.Maintenance.StartBackup().

If running in a client/server mode, you can use Raven.Backup.exe to perform manual or scheduled backups, or access the backup endpoint using HTTP directly.

When running from IIS, make sure to enable Windows Authentication for RavenDB's IIS application.

Only one backup operation may run at any given time.

Using the Raven.Backup utility

The utility Raven.Backup.exe is available from the Tools ZIP package in the download page.

Usage example:

Raven.Backup.exe --url=http://localhost:8080/ --database=Northwind --dest=C:\Temp\Foo --nowait --readkey

The backup utility will output the progress to the console window, pinging the server to get updated progress, unless ordered otherwise.

Parameters are as follows:

• url - The URL to the database that will be backed up. Server root URL (e.g. http://localhost:8080/) will point to system database; to point to a specific database, please use /databases/<database_name> endpoint (e.g. to backup ExampleDB use http://localhost:8080/databases/ExampleDB).
• dest - Backup destination. Has to be writable.
• (Optional) database - A database to operate on. If not specified, the operations will be performed on a default database.
• (Optional) nowait - By default the utility will ping the server and wait until backup is done, specifying this flag will make the utility return immediately after the backup process has started.
• (Optional) readkey - Specifying this flag will make the utility wait for key press before exiting.
• (Optional) incremental - When specified, the backup process will be incremental if destined for a folder where the previous backup lies. If dest is an empty folder, or it does not exist, a full backup will be created. For incremental backups to work, the configuration option Raven/Esent/CircularLog for esent has to be set to false or Raven/Voron/AllowIncrementalBackups (for voron) need to be set to true.
• (Optional) timeout - Timeout (in milliseconds) to use for requests.
• (Optional) username, password, domain, api-key - credentials used when authentication is required.

Remarks

Using Client API

Alternatively, you can use Client API to start a backup. API reference can be found here.

The backup operation is asynchronous. The backup process will start, and the request will complete before the backup process is completed.

You can check the status of the backup by querying the document with the key: "Raven/Backup/Status". The backup is completed when the IsRunning field in the document is set to false. The backup's current status can be tracked by querying the backup status document, which includes any errors that are occurring during the backup process.

Restoring SYSTEM database

Restoring a system database is an offline operation and it cannot operate on a running instance of RavenDB.

Raven.Server.exe --restore-source=[backup location] --restore-destination=[restore location] --restore-system-database

• restore-source=PATH - path to a folder where a database backup is present.
• restore-destination=PATH - path to a folder where a database will be restored.
• (Optional) restore-defrag - indicates if a database should be defragmented after restoring.
• restore-system-database - marks that SYSTEM database will be restored.

Restoring non-SYSTEM database

Restoring a non-SYSTEM database is an online operation, maning that the destination server must be running. Remember, that only one restore operation can be running simultaneously.

Raven.Server.exe --restore-source=[backup location] --restore-database=[URL to destination server]

• restore-source=PATH - path to a folder where a database backup is present (on a destination server).
• (Optional) restore-destination=PATH - path to a folder where a database will be restored (on destination server). If not specified, it will be located in a default data directory.
• (Optional) restore-defrag - indicates if databases should be defragmented after restoring.
• (Optional) restore-database-name=NAME - the name of a new database. If not specified, it will be extracted from the backup.
• restore-database=URL - marks that non-SYSTEM database will be restored and sets the URL to a destination server.
• (Optional) restore-no-wait - Return immediately without waiting for a restore to complete.
• (Optional) restore-start-timeout=TIMEOUT - The maximum timeout in seconds to wait for another restore to complete. Default: 15 seconds.

Remarks