You are currently browsing legacy 4.1 version of documentation. Click here to switch to the newest 4.2 version.

We can help you with migration to the latest RavenDB

Contact Us Now
see on GitHub

Backup



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:

    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);
    Note the usage of Cron scheduling when setting backup frequency.


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.

  • 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);

Tip

You can change youer Access Management in Amazon S3 so the user doing backup don't have full access, read more here.
for example:

{
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Sid": "VisualEditor0",
                    "Effect": "Allow",
                    "Action": "s3:PutObject",
                    "Resource": "arn:aws:s3:::BUCKET_NAME/*"
                },
                {
                    "Sid": "VisualEditor1",
                    "Effect": "Allow",
                    "Action": [
                        "s3:ListBucket",
                        "s3:GetBucketAcl",
                        "s3:GetBucketLocation"
                    ],
                    "Resource": "arn:aws:s3:::BUCKET_NAME"
                }
            ]
        }

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 backup
      taskId 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 LastRaftIndex LastRaftIndex { 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; }
      }

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