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 beginnig of the backup.
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
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
Raven.Backup.exe is available from the
/Backup folder in the ZIP package.
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 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 - Backup destination. Has to be writable.
database - A database to operate on. If not specified, the operations will be performed on a default database.
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.
readkey - Specifying this flag will make the utility wait for key press before exiting.
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.
timeout - Timeout (in milliseconds) to use for requests.
api-key - credentials used when authentication is required.
- Backups are not supported for Embedded databases when
Raven.Backup.exe is used.
Raven.Backup.exe has to be run with administrative privileges.
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 occuring during the backup process.