Backup

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:

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 * * * *",

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

• 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"
      },
  
      //Amazon S3 bucket settings.
      S3Settings = new S3Settings
      {
          AwsAccessKey = "your access key here",
          AwsSecretKey = "your secret key here",
          AwsRegionName = "OPTIONAL",
          BucketName = "john-bucket",
      },
  
      //Amazon Glacier settings.
      GlacierSettings = new GlacierSettings
      {
          AwsAccessKey = "your access key here",
          AwsSecretKey = "your secret key here",
          AwsRegionName = "OPTIONAL",
          VaultName = "john-glacier",
      }
  
  };
  var operation = new UpdatePeriodicBackupOperation(config);
  var result = await docStore.Maintenance.SendAsync(operation);

{
            "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"
                }
            ]
        }

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; }
    }