Backup
-
Create a backup of your data to secure it or to preserve a copy of it in its current state for future reference.
-
RavenDB's ongoing Backup task is designed to run continuously.
You can run it as a one-time operation as well, using export or executing a backup-task immediately. -
In this page:
Backup Types
Logical-Backup
-
Data is backed-up in compressed JSON files.
-
During restoration, RavenDB -
- Re-inserts all data into the database.
- Re-indexes the data.
-
Restoration Time is therefore slower than that required when restoring a Snapshot.
-
Backup size is significantly smaller than that of a Snapshot.
-
Code Sample:
Note the usage of Cron scheduling when setting backup frequency.var config = new PeriodicBackupConfiguration { LocalSettings = new LocalSettings { //Backup files local path FolderPath = @"E:\RavenBackups" }, //Full Backup period (Cron expression for a 3-hours period) FullBackupFrequency = "0 */3 * * *", //Type can be Backup or Snapshot BackupType = BackupType.Backup, //Task Name Name = "fullBackupTask", }; var operation = new UpdatePeriodicBackupOperation(config); var result = await docStore.Maintenance.SendAsync(operation);
Snapshot
-
Snapshot backups are available for Enterprise subscribers only.
A SnapShot is a compressed binary duplication of the database and journals file structure at a given point-in-time. -
During restoration -
- Re-indexing is not required.
- Re-inserting data into the database is not required.
-
Restoration is typically faster than that of a logical backup.
-
Snapshot size is typically larger than that of a logical backup.
-
Code Sample:
//Type can be Backup or Snapshot BackupType = BackupType.Snapshot,
Basic Comparison Between a Logical-Backup and a Snapshot:
Backup Type | Stored Format | Restoration speed | Task characteristics | Size |
---|---|---|---|---|
Snapshot | Compressed Binary Image | Fast | Ongoing Background Task | Larger than logical-backup's |
Logical backup | Compressed Textual Data | Slow | Ongoing Background Task | Smaller than Snapshot's |
Make sure your server has access to the local backup path.
Verify that RavenDB is allowed to store backup files in the path set in LocalSettings.FolderPath
.
Backup Scope
As described in the overview, a backup task can create full and incremental backups.
- Both backup operations add a single new backup file to the backup folder each time they run. leaving existing backup files untouched.
- Both are operated by an ongoing task.
Full Backup
-
There are no preliminary conditions to creating a full backup. Any node can perform this task.
-
To run a full backup, set
FullBackupFrequency
.//Full Backup period (Cron expression for a 6-hours period) FullBackupFrequency = "0 */6 * * *",
Incremental Backup
- An incremental-backup file is always in JSON format. It is so even when the full backup it supplements is a binary snapshot.
-
Incremental Backup ownership
- An incremental backup can be created only by the node that currently owns the backup task.
- The ownership is granted dynamically by the cluster.
- A node can run the incremental backup task, only after creating a full backup at least once.
-
To run an incremental backup, set
IncrementalBackupFrequency
.//Cron expression: set incremental backup period ("*/20 * * * *" is a 20-minutes period) IncrementalBackupFrequency = "*/20 * * * *",
Backup to Remote Destinations
-
Backups can be made locally, as well as to a set of remote locations including -
- A network path
- An FTP/SFTP target
- Amazon S3
- Azure Storage
- Amazon Glacier
-
RavenDB will store data in a local folder first, and transfer it to the remote destination from the local one.
- If a local folder hasn't been specified, RavenDB will use the
temp folder defined in its Storage.TempPath setting.
If Storage.TempPath is not defined, the temporary files will be created at the same location as the data file.
In either case, the folder will be used as temporary storage and the local files deleted from it when the transfer is completed. - If a local folder has been specified, RavenDB will use it both for the transfer and as its permanent local backup location.
- If a local folder hasn't been specified, RavenDB will use the
temp folder defined in its Storage.TempPath setting.
-
Remote Backup Destinations Code Sample:
var config = new PeriodicBackupConfiguration { LocalSettings = new LocalSettings { FolderPath = @"E:\RavenBackups" }, //FTP Backup settings FtpSettings = new FtpSettings { Url = "192.168.10.4", Port = 8080, UserName = "John", Password = "JohnDoe38" }, //Azure Backup settings AzureSettings = new AzureSettings { StorageContainer = "storageContainer", RemoteFolderName = "remoteFolder", AccountName = "JohnAccount", AccountKey = "key" } }; var operation = new UpdatePeriodicBackupOperation(config); var result = await docStore.Maintenance.SendAsync(operation);
Initiate Immediate Backup Execution
The Backup task runs continuously as an ongoing task, but you can also operate the task immediately if you wish to.
-
To execute an existing backup task immediately, use the
StartBackupOperation
method.
var operation = new UpdatePeriodicBackupOperation(config); var result = await docStore.Maintenance.SendAsync(operation); //run a backup task immediately await docStore.Maintenance.SendAsync(new StartBackupOperation(true, result.TaskId));
-
Definition:
public StartBackupOperation(bool isFullBackup, long taskId)
-
Parameters:
Parameter Type Functionality isFullBackup bool true: full backup
false: incremental backuptaskId long The task ID returned by RavenDB
-
-
To verify the execution results, use the
GetPeriodicBackupStatusOperation
method.
//Provide GetPeriodicBackupStatusOperation with the task ID returned by RavenDB var backupStatus = new GetPeriodicBackupStatusOperation(result.TaskId);
- Return Value:
The status structure that GetPeriodicBackupStatusOperation returns, is filled with backup parameters you previously configured and with the execution results.
public class PeriodicBackupStatus : IDatabaseTaskStatus { public long TaskId { get; set; } public BackupType BackupType { get; set; } public bool IsFull { get; set; } public string NodeTag { get; set; } public DateTime? LastFullBackup { get; set; } public DateTime? LastIncrementalBackup { get; set; } public DateTime? LastFullBackupInternal { get; set; } public DateTime? LastIncrementalBackupInternal { get; set; } public LocalBackup LocalBackup { get; set; } public UploadToS3 UploadToS3; public UploadToGlacier UploadToGlacier; public UploadToAzure UploadToAzure; public UploadToFtp UploadToFtp; public long? LastEtag { get; set; } public string FolderName { get; set; } public long? DurationInMs { get; set; } public long Version { get; set; } public Error Error { get; set; } public long? LastOperationId { get; set; } }
- Return Value:
Recommended Precautions
-
Don't substitute RavenDB's backup procedures with simply copying the database folder yourself.
The official backup procedure satisfies needs that simply copying the database folder does not. E.g. -- A reliable point-in-time freeze of backed up data.
- An ACIDity of backed-up data, to keep its independence during restoration.
-
Regularly remove backup files.
Note that RavenDB does not automatically remove backup files. As they continue to aggregate, it is important that you take care of their regular removal.
You can use services like crontab (a linux scheduling procedure) to create an old-backups-removal routine. -
Locate backup files in a location other than your database's.
Note that backup files are always stored in a local folder first (even when the final backup destination is remote).
Make sure that this local folder is not where your database is stored, as a precaution to keep vacant database storage space.