Skip to main content

One-time database backup

  • Database backups are typically scheduled using periodic backup tasks and created automatically according to the defined schedule.
    However, you can also back up any database on demand, whenever needed.

  • You can define a one-time backup configuration and run it to create a backup immediately.

  • You can also trigger any periodic backup task defined for your database, to create a backup now.

Running a one-time backup operation using the client API​

Defining and running a one-time backup operation​

To define and run a one-time backup operation:

  • Define a backup configuration using a BackupConfiguration instance.
  • Pass the instance to BackupOperation to run the backup.

Example:

// Set the backup configuration
var config = new BackupConfiguration
{
    // Set backup type
    BackupType = BackupType.Backup, 
    
    // Store in a local folder
    LocalSettings = new LocalSettings
    {
        FolderPath = @"D:\RavenDB\Backups"
    }
};

// Run backup operation
Operation<StartBackupOperationResult> op = 
    await store.Maintenance.SendAsync(new BackupOperation(config));

Setting backup type:​

  • Set the backup type using the backup configuration BackupType enum property.
    You can assign it with BackupType.Backup to create logical backups,
    or with BackupType.Snapshot for snapshot images.

    e.g.,

    var config = new BackupConfiguration
    {
        // ...

        BackupType = BackupType.Snapshot,
        
        // ...
    };

Setting storage destinations:​

  • Set storage destinations using the backup configuration storage classes:

    • Local path: LocalSettings
    • Amazon S3: S3Settings and AmazonSettings
    • Amazon Glacier: GlacierSettings and AmazonSettings
    • Azure Blob Storage: AzureSettings
    • FTP server: FtpSettings
    • Google Cloud Storage: GoogleCloudSettings

    e.g.,

    var config = new BackupConfiguration
    {
        // ...

        LocalSettings = new LocalSettings
        {
            FolderPath = backupPath
        },
        AzureSettings = new AzureSettings
        {
            // Use your Azure credentials here
        },

        // ...
    };

  • See destinations-related syntax

Setting encryption:​

Set backup encryption using the backup configuration BackupEncryptionSettings property.

  • Snapshots are exact images of the database, and as such are automatically encrypted when the database is encrypted (using the same encryption key as the database) or unencrypted when the database is not encrypted.

  • Logical backups can be encrypted or not, regardless of the database encryption.

    • Use BackupEncryptionSettings.EncryptionMode to select if and how backups should be encrypted.
      Available options are:

      • EncryptionMode.None - Do not encrypt backups
      • EncryptionMode.UseDatabaseKey - Encrypt the backup using the same encryption key as the database.
        This option is relevant only when the database is encrypted.
      • EncryptionMode.UseProvidedKey - Use a key provided by the user.
        This option can be used both when the database is encrypted and when it isn't.
        If you use your own key, provide it via BackupEncryptionSettings.Key.

      e.g.,

      var config = new BackupConfiguration
      {
         // ...

         // Encrypt a logical backup using a user-provided key
         BackupEncryptionSettings = new BackupEncryptionSettings
         {
             // A Base64-encoded encryption key
             Key = "0eZ6g9f2k+GxH8c4Yv4xNwqzJ48m3o3x7lKQyqgQXct=",
             EncryptionMode = EncryptionMode.UseProvidedKey
         }

         // ...
      };

  • See BackupEncryptionSettings and EncryptionMode syntax

Aborting a running backup operation​

To abort a backup operation:

  • Pass the operation ID to KillOperationCommand.
  • Also pass to KillOperationCommand the operation node tag, so it would target the cluster node that runs the backup operation.

Example:

  // Set the backup configuration
var config = new BackupConfiguration
{
    // Set backup type
    BackupType = BackupType.Backup, 
    
    // Store in a local folder
    LocalSettings = new LocalSettings
    {
        FolderPath = @"D:\RavenDB\Backups"
    }
};

// Run backup operation
Operation<StartBackupOperationResult> op = 
    await store.Maintenance.SendAsync(new BackupOperation(config));

// Abort the backup by killing the running operation
long operationId = op.Id;
string nodeTag = op.NodeTag;

await store.Commands(store.Database).ExecuteAsync(
    new KillOperationCommand(operationId, nodeTag));

Note that after aborting the backup operation, you may need to manually clean up:

  • Partial local files, left while creating the backup.
  • Partial or temporary remote uploads.

Syntax​

Backup configuration​

Backup configuration

class BackupConfiguration
{
    BackupType BackupType
    BackupUploadMode BackupUploadMode
    SnapshotSettings SnapshotSettings
    BackupEncryptionSettings BackupEncryptionSettings
    int? MaxReadOpsPerSecond
    LocalSettings LocalSettings
    S3Settings S3Settings
    GlacierSettings GlacierSettings
    AzureSettings AzureSettings
    FtpSettings FtpSettings
    GoogleCloudSettings GoogleCloudSettings
}

PropertyTypeDescription
BackupTypeBackupTypeBackup type (snapshot or logical backup)
BackupUploadModeBackupUploadModeUpload mode (via local storage or directly to destination)
SnapshotSettingsSnapshotSettingsSnapshot settings
BackupEncryptionSettingsBackupEncryptionSettingsEncryption settings
MaxReadOpsPerSecondint?Maximum number of read operations per second allowed during backup.
LocalSettingsLocalSettingsLocal storage settings
S3SettingsS3SettingsAmazon S3 backup settings
GlacierSettingsGlacierSettingsAmazon Glacier backup settings
AzureSettingsAzureSettingsAzure backup settings
FtpSettingsFtpSettingsFTP-based backup settings
GoogleCloudSettingsGoogleCloudSettingsGoogle Cloud backup settings

Classes and enums used in the backup configuration​

A backup configuration property that defines the backup type.

enum BackupType
{
    Backup,
    Snapshot
}

PropertyDescription
BackupLogical backup
SnapshotSnapshot image

A backup configuration property that defines backup encryption settings.

class BackupEncryptionSettings
{
    string Key
    EncryptionMode EncryptionMode
}

PropertyTypeDescription
KeystringAn encryption key provided by the user.
Used only if EncryptionMode.UseProvidedKey is selected.
If EncryptionMode.UseDatabaseKey is selected, the database encryption key is used and Key is ignored.
EncryptionModeEncryptionModeThe mode of encryption applied to the backup.
None - No encryption.
UseDatabaseKey - Use the database key for encryption.
UseProvidedKey - Use a key provided by the user.

Backup destinations classes​

A backup configuration property that defines local storage settings.

class LocalSettings : BackupSettings
{
    string FolderPath
    int? ShardNumber
}

PropertyTypeDescription
FolderPathstringPath to a local folder.
When set, backups are kept in this path and will not be deleted.
ShardNumberint?An optional shard number, so the backup can be kept in the local path of a specific shard when a sharded database is used.

A backup configuration property that defines Amazon S3 storage settings.

class S3Settings : AmazonSettings
{
    string BucketName
    string CustomServerUrl
    bool ForcePathStyle
    S3StorageClass? StorageClass
}

PropertyTypeDescription
BucketNamestringS3 Bucket name.
CustomServerUrlstringCustom S3 server URL.
Used when targeting a custom server.
ForcePathStyleboolForce path style in HTTP requests.
false - use virtual host style.
true - use path style.
StorageClassS3StorageClass?Optional AWS S3 storage class for uploaded objects.

Triggering a backup task to run a backup operation immediately​

Each periodic backup task, including server-wide derived tasks, can be triggered to run a backup operation immediately, outside of its schedule.

Triggering a regular backup task to run a backup operation immediately
Triggering a server-wide derived task to run a backup operation immediately

Running a one-time backup operation using Studio​

Defining and running a one-time backup operation​

To back up a database immediately:

A. Define basic backup options​

Define basic settingsDefine basic settings

  1. Backup upload mode
    Select the preferred upload mode:

    • Default - store the backup locally before uploading it to any remote destination.
      Storing the backup locally provides a safety measure in case the upload fails.
    • Direct upload - upload the backup directly to its destinations without storing locally.
      Direct upload can be used, for example, when the local storage space is limited.

  2. Backup type
    Select the type of backup to create:

    • Backup - create a logical backup.

    • Snapshot - create a snapshot image.

      When snapshot is selected, a few additional options are available:

      • Compression algorithm
        Defines the compression algorithm used for the snapshot image.
        Available algorithms are Zstd and Deflate.
      • Compression level
        Defines the level of compression applied to the snapshot image.
        Options include:
        No Compression: No compression applied
        Fastest: Prioritizes speed, resulting a larger image file
        Optimal: Balances compression efficiency and CPU usage
        Smallest size: Achieves the smallest image size at the highest CPU cost.
      • Exclude indexes
        Enable this option to exclude index data from the snapshot, reducing image size and transfer time.
        Note that this will increase restore time, as indexes will need to be recreated from their definitions and rebuilt by indexing all documents relevant to each index.

  3. Set max read operations per second
    Enter the maximum number of read operations per second that the task is allowed to make during backup.
    Setting a read operations limit can reduce the impact of backup operations on server performance.

B. Set backup encryption options​

Backup encryptionBackup encryption

Use this section to configure encryption options for a logical backup (when the selected backup type is backup).

  • These settings do not apply to a snapshot because a snapshot is an exact replica of the database and automatically reflects its encryption:

    • If the database is encrypted, the snapshot will be encrypted as well, using the database encryption key.
    • If the database is not encrypted, the snapshot will not be encrypted either.

  • A logical backup, on the other hand, can be encrypted or unencrypted regardless of the database encryption. You can:

    • Create an unencrypted backup, even if the database is encrypted.
    • Encrypt the backup for an encrypted database using either the database encryption key or your own encryption key.
    • Encrypt the backup for an unencrypted database using your own encryption key.

Create a non-encrypted logical backup:​

  • To create a non-encrypted backup, disable the Encrypt backup option.

    Disable encryptionDisable encryption

  • If the database you want to back up is encrypted and you disable backup encryption, a confirmation button will appear so you can affirm your choice, as creating a non-encrypted backup for an encrypted database may have security implications.

    Confirm non-encrypted backup for encrypted databaseConfirm non-encrypted backup for encrypted database

Create an encrypted logical backup:​

  • To create an encrypted backup, enable the Encrypt backup option.

    Enable encryptionEnable encryption

  • If the database is encrypted, you will be given the choice to use either the database encryption key or your own key.

    • Use the database encryption key for simplicity, as you won't need to manage a separate encryption key for backups.

      Use database encryption keyUse database encryption key

    • Or use your own encryption key for more control over backup encryption, e.g., to use a different key rotation policy for backups than for the database.

      Use own encryption keyUse own encryption key

      You will be given access to a key generator to create a strong encryption key, either use it or provide your own Base64 key.

      Encryption key generatorEncryption key generator

      Be sure to secure your encryption key, as without it you will not be able to restore your backups!

  • If the database is not encrypted, you can still generate or enter your own key to encrypt the backups.

C. Choose where to store the backup​

Available storage destinationsAvailable storage destinations

You can select one or more storage locations for the backup, both local and remote.

  • Each storage location has its own specific settings to configure.
    e.g., Backup directory for local storage or Bucket name for Amazon S3.
    Be sure to fill in the required settings for each selected storage location.

    Local storage settingsLocal storage settings

  • The Backup Upload Mode setting defined above determines whether to store the backup locally before sending it to any remote destination.

D. Run the backup operation​

Run the backupRun the backup

Click Backup Now to back up the database by your settings.

Backup is runningBackup is running

  • While the backup is being created, you can follow its progress.
  • To abort the backup operation, e.g., if it takes longer than expected and you need to free up server resources, click the Abort button.
    Note that aborting the operation may require manual cleanup of partial local files and/or remote uploads.

Triggering a backup task to run a backup operation immediately​

Each periodic backup task, including server-wide derived tasks, can be triggered to run a backup operation immediately, outside of its schedule.

Triggering a regular backup task to run a backup operation immediately
Triggering a server-wide derived task to run a backup operation immediately

In this article