RavenDB version 2.5. Other versions:

Backup and Restore

RavenDB supports backup and restore. Backups can be performed while the database in online and accepting 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. You can do that by configuring your backup solution to take backups of Raven's data directory.
  • Using RavenDB's own backup & restore system. 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, it is the state of the database at the start of the backup.

Unlike backups, restores are offline operation. You cannot restore to a running database (indeed, the notion makes little sense).

Backward compatibility

RavenDB relies on 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 are looking to move a database content between different Operating System versions, you should use the Import / Export function, done using Raven.Smuggler.

Initiating a backup

When running in embedded mode, all you need is to call the method DocumentDatabase.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 directly using HTTP.

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

Only one backup operation may run at any given time.

The utility has to be run with administrative privileges

Using the Raven.Backup utility

The utility Raven.Backup.exe is available from the /Tools folder in both the distribution and nuget packages.

Usage example:

    Raven.Backup.exe --url=http://localhost:8080/ --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 - Required. The URL to database that will be backuped. 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 - Required. Backup destination. Has to be writable.
  • nowait - Optional. 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.
  • readkey - Optional. Specifying this flag will make the utility wait for key press before exiting.
  • incremental - Optional. When specified, the backup process will be incremental when done to a folder where a 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 has to be set to false.

Backups are not supported for Embedded databases.

Using the HTTP API

Alternatively, you can send an HTTP POST command to the /admin/backup endpoint as follows:

    curl -X POST http://localhost:8080/admin/backup -d "{ 'BackupLocation': 'C:\\Backups\\2010-05-06' }"

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 current status can be tracked by querying the backup status document, this includes any errors that occur during the backup process.

The backup of an encrypted database contains the encryption key (Raven/Encryption/Key) as a plain text. This is required to make RavenDB able to restore the backup on a different machine.

How to restore a database

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

In embedded mode, you can initiate the restore operation by calling DocumentDatabase.Restore(), or through the command line:

    Raven.Server.exe -src [backup location] -dest [restore location] -restore

If the restore location doesn't exists, RavenDB will create it.

You cannot restore to an existing database data directory, the restore operation will fail if it detects that the restore operation will overwrite existing data. If you need to restore to an existing database data directory, shutdown the database instance and delete the data directory.

Unlike backups, restores are fully synchronous.

Comments add new comment

The comments section is for user feedback or community content. If you seek assistance or have any questions, please post them at our support forums.

Ulrik
REPLY Posted by Ulrik on

I found this useful when doing a backup/restore between machines: You must run the following command on the restored "Data" file (not directory) esentutl /d Data

Frederik Vig
REPLY Posted by Frederik Vig on

If you have multiple databases, using just the server URL will only backup the default database. To backup a specific database use --url=<server url>:<port>/databases/databasename/

Robert Johansson
REPLY Posted by Robert Johansson on

Hi! Thanks for this instructional site! I'm trying to make a backup from my database with the following command Raven.Backup.exe --url=http://localhost:8080/ --dest=C:\Temp but I get an error message saying Sending Json < "Backuplocation": "C:\Temp" > to localhost:8080 The remote server returned an error: <401> Unauthorized.

What am I doing wrong?

Ayende Rahien
REPLY Posted by Ayende Rahien on

You have to run this command from an elevated admin command prompt.

Robert
REPLY Posted by Robert on

Thanks for your reply, I'm not sure what that means. Do I need to change directory to run this? I'm logged as an administrator on the server.

Ayende Rahien
REPLY Posted by Ayende Rahien on

Right click on cmd, Run As Admin, then run the command.

Robert
REPLY Posted by Robert on

I must be doing something wrong, when I run as admin I come to the prompt C:\Users\Administrator, when I run the command I get the same error message as before. I also tried to export the data using this command Raven.Smuggler out http://localhost:8080 dump.raven but I only got crap (lots of random symbols) in the file when I opened it, a friend says it's because the data is encrypted. Could that be the problem?

Ayende Rahien
REPLY Posted by Ayende Rahien on

Please ask this in the mailing list. This is NOT a support channel

Robert
REPLY Posted by Robert on

Ok, thanks for your help!

Tom
REPLY Posted by Tom on

I had to add Raven.Abstractions.dll to the backup directory to avoid an exception stating that the dll was missing; further details on request.

could add Ravens Server directory to the Path variable?

Fitzchak Yitzchaki
REPLY Posted by Fitzchak Yitzchaki on

The Raven.Abstractions.dll should be there on the first place, if you used the zip download. Yes, I don't see why not.

Ben Shaw
REPLY Posted by Ben Shaw on

How do I restore a periodic backup?

Ayende Rahien
REPLY Posted by Ayende Rahien on

raven.smuggler.exe in http://raven-db:8080 c:\path-to-backup --database=db-name --incremental

Charlie Barker
REPLY Posted by Charlie Barker on

Can you compress a backup as it is being created?

Steve
REPLY Posted by Steve on

It should be mentioned that when running a restore from the command line it does not automatically get added to the system database and therefore does not show up until this is done (as it does with a restore from the web client interface)

Also how can I restore an incremental backup?

praveen
REPLY Posted by praveen on

I have restored my db, however I am unable to view the database in Raven studio. Please help me to solve this issue.

Regards, Praveen

Douglas McLaughlin
REPLY Posted by Douglas McLaughlin on

There is no such method as DocumentDatabase.StartBackup();

Ben
REPLY Posted by Ben on

Command line restore is only really appropriate for the system database

Swati
REPLY Posted by Swati on

Is there a way to do differential and log back up ? Thanks.

SUBMIT COMMENT