Skip to main content

Overview

Backup recurrence​

You can configure periodic backup tasks that automatically create backups at predefined time intervals based on your schedule, type, scope, and other settings.
You can also execute a one-time backup when needed.

Periodic backup tasks​

Periodic backup tasks are a key tool in ensuring your data safety, as they run in the background and automatically create backups on a predefined schedule.

  • When creating a backup task using the client API, backups are scheduled using cron expressions.
    e.g.,
    • 0 */6 * * * - 0 minutes past the hour, every 6 hours
    • */20 * * * * - every 20 minutes
  • The execution of a running backup operation can be delayed if needed. For example, while performing maintenance operations on the server.

Learn to define a periodic backup task using the client API
Learn to define a periodic backup task via Studio

One-time backup operation​

You can run an immediate one-time backup operation to safeguard your data, e.g., before performing a risky change on the database.

One-time backups are also useful when you want to create a backup at a specific point in time that doesn't fit the schedule of your periodic backup tasks.

Learn to create a one-time backup using the client API
Learn to create a one-time backup via Studio

Backup type​

You can back up your data in a JSON-based logical backup, that is typically smaller and quicker to transfer, or as a binary snapshot image, that is typically faster to restore.

Backup typeFormatRestore speedSize
Logical backupCompressed textual data - JSONSlower than a snapshotSmaller than a snapshot
Snapshot imageCompressed binary imageFaster than a logical backupLarger than a logical backup

Logical backup​

A logical backup is a compressed JSON dump of the database content at a given point in time, including documents, index definitions (but not the actual index data), ongoing tasks, and additional data.

  • Both full and incremental backups are stored in a JSON-based format.
  • A full logical backup is typically much smaller than an equivalent snapshot image, but restore time is longer because documents and index definitions need to be inserted into the newly created database.
  • Following the restore operation, the database is scanned and re-indexed according to the index definitions.
    This operation can be time-consuming when performed on large datasets.

Snapshot image​

A snapshot is a compressed binary image of the entire database structure at a given point in time, including document data, journals, indexes, ongoing tasks, and additional data.

  • A snapshot is typically larger than an equivalent logical backup, but restore time is reduced because documents and index definitions do not need to be inserted into the database, and subsequent re-indexing is not required.
  • Incremental backups following the initial complete snapshot are stored in JSON format, similar to logical backups. They do not carry index or change vectors data as the full snapshot does.

Backup Content​

Backups contain both database-level and cluster-level content, as detailed below.

Database-level data​

ContentIncluded in logical backupsIncluded in snapshots
Documents & Revisions✔✔
Attachments✔✔
Counters✔✔
Time-Series✔✔
Change Vector dataChange Vectors are not preserved,
but recreated after restoring.		✔
Tombstones✔✔
Conflicts✔✔

Cluster-level data​

ContentIncluded in logical backupsIncluded in snapshots
Database Record✔✔
Compare-exchange values✔✔
Identities✔✔
IndexesIndexes are not preserved,
but rebuilt after restoring
from backed up index definitions.		✔
Ongoing Tasks configuration✔✔
Subscriptions✔✔

Backup scope​

A backup task can create full and/or incremental backups.

  • Each time a backup task (full or incremental) is executed, a single new backup file is added.
  • Existing backup files are not modified or deleted by the task, unless a retention policy is set.

Full Backup​

Full logical backup:​

A full logical backup contains the whole database content, except for full indexes and change vectors.

  • A full backup, containing one compressed file with the entire database content, is always created in a new subfolder in the backup directory.
    e.g., a full backup created every 6 hours:
    FullBackupFrequency = "0 */6 * * *"
  • An incremental backup, containing one compressed file with only the changes since the last backup, is always added to the folder of the last full backup.
    e.g., an incremental backup created every 20 minutes:
    IncrementalBackupFrequency = "*/20 * * * *"
  • Location
    When stored locally, a full backup is always created in a new subfolder in the backup directory.
  • Format:
    Compressed JSON dump.
  • Indexes:
    The backup does not include the full index data, but just index definitions.
    When the database is restored, indexes are recreated from their definitions and rebuilt by indexing all documents relevant to each index.
  • Change vectors:
    Change vectors are not included in the backup, but recreated after restoring.
  • Task ownership:
    There are no preliminary conditions for creating a full backup. Any node can perform this task.

Full snapshot image:​

A full snapshot image is a duplication of the entire database content.

  • Location
    When stored locally, a full backup is always created in a new subfolder in the backup directory.
  • Format:
    Compressed binary image.
  • Indexes:
    Included
  • Change vectors:
    Included
  • Task ownership:
    There are no preliminary conditions for creating a full backup. Any node can perform this task.

Incremental Backup​

An incremental backup contains only the changes made to the database since the last backup, to save storage space and reduce backup time.

When an incremental-backup task is executed, it checks for the existence of a backup file.

  • If a backup file is not found, the task will create a full backup.
  • Subsequent backups will be incremental.
  • Location
    When stored locally, incremental backups are always added to the folder of the last full backup they supplement.
    If no full backup is found, a full backup will be created first in a new subfolder, before starting with the regular incremental backup routine.
  • Format:
    Compressed JSON dump.
    Incremental backups are always in JSON format, even when supplementing a binary snapshot image.
  • Indexes:
    Incremental backups do not include the full index data, but just index definitions (if updated since the previous backup).
    When the dataset is restored, indexes are recreated from their definitions and rebuilt by indexing all documents relevant to each index.
  • Change vectors:
    Change vectors are not included in incremental backups, but recreated after restoring.
  • Task ownership:
    The ownership of an incremental backup task is granted dynamically by the cluster.
    An incremental backup can be executed only by the same node that currently owns the backup task.
    A node can run an incremental backup only after running a full backup at least once.

Typical Configuration​

A typical backup configuration includes a full database backup at regular intervals and incremental backups at shorter intervals, stored locally as well as exported to a remote destination.
e.g.,

  • A full backup created every 6 hours:
    FullBackupFrequency = "0 */6 * * *"
  • And an incremental backup added every 20 minutes:
    IncrementalBackupFrequency = "*/20 * * * *"

Overlap between full and incremental backup tasks:​

If a backup task creates both full and incremental backups, and their schedules overlap, the full backup will take precedence, and the incremental backup will be skipped.

For example, if a full backup is scheduled to run every 6 hours and an incremental backup every 20 minutes, the incremental backup scheduled at the same time as the full backup will be skipped.

Backup storage​

Local and remote storage​

You can store your backups in a local directory and/or in one or more remote destinations.

Available destinations:​

  • A local path
  • An FTP/SFTP target
  • Azure Storage
  • Amazon S3
  • Amazon Glacier
  • Google Cloud

Upload mode:​

When using a remote destination (like an FTP destination or an S3 bucket), you can select the upload mode.

  • When set to Default, backups are stored locally and exported from the local directory.
    You may prefer this mode if you want to ensure that backup files are not lost even if uploading to the remote destination fails, or if you're storing backups locally anyway in addition to exporting them.

    • If a local folder was selected as one of the storage destinations, RavenDB will use it to store both the temporary backup files created during the upload process and the permanent backup files.
    • If a local folder was not selected, RavenDB will use the folder defined by the Storage.TempPath configuration key.
      If Storage.TempPath is not defined, the temporary files will be kept in the same location as the RavenDB data file.
      In either case, the folder will be used for temporary storage, and the backup files deleted from it when the transfer is completed.

  • When set to Direct upload, backups are transferred directly to their remote destination without being stored locally first.
    You can use this mode if you want to avoid storing backups locally, e.g., for security reasons, or to save local storage space.

Overriding storage settings with an external script:​

An external script can be executed at runtime to override storage settings.
This can be useful, for example, if you want to fetch the credentials for the storage destination from a secure location, to avoid keeping secrets in the task configuration.

  • A script is defined for a specific storage destination.
    If defined for the local storage, for example, it can set local path to D:\RavenDB\Backup.
    • The script is executed before each backup operation, and is required to return the storage settings so the backup task can apply them.
    • The script needs to return a JSON output with the settings in a structure suitable for the storage destination.
      e.g., if intended for local storage, it must include a FolderPath property with the path as its value, and potentially a ShardNumber property.
    • The script must be executed on the node that runs the backup operation.
  • To use an external script, these parameters need to be provided:
    • Exec - The script executor.
      This is the application that runs the external script.
      For Windows, for example, the executor can be powershell, bash, or another application.

      You can provide this parameter in the form of a path to the executor, or, if defined, as a system variable pointing at it.

      e.g.,
      powershell or C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
    • Arguments - Flags or parameters required by the executor, including the path to the external script.
      e.g.,
      • Point powershell to a script kept in D\RavenDB\Backups: 
        -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "D\RavenDB\Backups\local-settings.ps1"
      • Content of local-settings.ps1, which outputs the local storage path in JSON format: 
        @{ FolderPath = "D:\RavenDB\Backups\fullBackups" } | ConvertTo-Json -Compress
    • Timeout - The maximum time (in ms) that RavenDB will wait for the executor to return the JSON output.
      If the time limit is exceeded, the backup operation will fail.
      e.g., 10000

Naming and backup folder content​

Naming:​

Backup folders and files are named automatically.

  • Folder names are constructed of:

    • Current Date and Time
    • Backed-up Database Name
    • Owner-Node Tag
    • Backup Type ("backup" for a logical backup or "snapshot" for a snapshot image)

  • File names are constructed of:

    • Current Date and Time
    • Backup Scope ("full-backup" or "incremental-backup")
    • Backup Type ("backup" for a logical backup or "snapshot" for a snapshot image)

  • For example:

    • 2025-12-26-16-17.ravendb-Products-A-backup - The name automatically given to a backup folder.
      • "2025-12-26-16-17" - Backup date and time
      • "Products" - Backed-up database name
      • "A" - Executing node's tag
      • "backup" - Backup type (backup/snapshot)
    • 2025-12-26-16-17.ravendb-full-backup - The name automatically given to the full backup file within the folder.
      Subsequent incremental backups will be added to the folder with an "incremental-backup" suffix.

Backup folder content:​

A backup folder always contains a single full-backup file, and optionally a list of incremental-backup files that supplement it.
Each incremental-backup file contains only the changes made in the database since the previous backup (full or incremental).

  • For example -
    2018-12-26-09-00.ravendb-full-backup
    2018-12-26-12-00.ravendb-incremental-backup
    2018-12-26-15-00.ravendb-incremental-backup
    2018-12-26-18-00.ravendb-incremental-backup

Encryption​

Logical backup encryption:​

When creating a logical backup, the following options are available:

  • If the database the backup is made for is unencrypted:

    • You can create an unencrypted backup.
    • You can create an encrypted backup using your own encryption key.

  • If the database the backup is made for is encrypted:

    • You can create an unencrypted backup.
    • You can create an encrypted backup using the database encryption key.
    • You can create an encrypted backup using your own encryption key.

Snapshot image encryption:​

A snapshot is an exact image of the database, and its encryption matches the database's encryption as well:

  • If the database is unencrypted, its snapshots will also be unencrypted.

  • If the database is encrypted, its snapshots will also be encrypted, using the database encryption key.

Incremental backup encryption:​

The Incremental backups of an encrypted full backup (either a logical backup or a snapshot) are encrypted as well, using the same encryption key as the full backup.

Learn to encrypt your backups using the client API
Learn to encrypt your backups via Studio

Compression​

  • A backup always consists of a single compressed file.
    This applies to both full (logical and snapshot) and incremental backups.
  • Backup files are compressed using gzip.

Retention policy​

By default, backups are stored indefinitely. To prevent the accumulation of outdated backup files and keep storage usage under control, you can set a retention policy:

  • A retention period is set.
  • If a backup's age exceeds the set period, the backup will be deleted during the next scheduled backup task.

A full backup and its corresponding incremental backups are always deleted as a group when the age of all incremental backups exceeds the retention period.

Learn to set a retention policy using the client API
Learn to set a retention policy via Studio

Server-wide backup​

A database backup task applies to one database only.
If your server hosts multiple databases, keeping a separate backup task for each of them may become difficult, especially if some databases require multiple backup tasks.

A server-wide task solves this difficulty by allowing you to define the backup configuration only once. The server then applies your configuration to all databases as derived per-database backup tasks.

  • The same features available for single-database backup tasks are supported for server-wide derived tasks.
    For example, your configuration can set full and incremental backups, and define a retention policy.
  • Modifying, disabling, or deleting the parent server-wide task applies to all derived database tasks.
  • In addition, you can access each derived task directly to check its schedule and other details or to create an immediate backup for the database.

The server-wide configuration​

The configuration you set for a server-wide backup task is similar to the configuration of a regular database backup task, with the following changes:

Excluding databases from the backup:​

By default, derived backup tasks are created for all databases to schedule a backup routine for the entire server.
You can, however, exclude specific databases from the backup in the task configuration.

e.g., you may prefer to exclude a certain database from the server-wide configuration and schedule a different backup routine for it, with a different storage destination and different time intervals, using a regular database backup task.

Server-wide backups storage:​

As multiple databases are backed up, the backups for each database are kept separately from those of other databases.

  • Local storage

    • Use the task configuration to define a root backup path.
      e.g., D:\RavenDB\Backups
    • Each database task will keep backups in a subfolder named after the database, under the root backup path.
      e.g., backups for the Products database will be stored under: D:\RavenDB\Backups\Products

  • FTP destination

    • Use the task configuration to define a root URL.
      e.g., ftp://myserver.com/backups
    • Each database task will send backups to a subfolder named after the database, under the root URL.
      e.g., backups for the Products database will be sent to: ftp://myserver.com/backups/Products

  • Other remote destinations (S3, Azure, Glacier, GoogleCloud)

    • Use the task configuration to define a root remote folder name.
      e.g., ravendb/backups
    • Each database task will send backups to a subfolder named after the database, under the root folder name.
      e.g., backups for the Products database will be sent to: ravendb/backups/Products

Server-wide encryption settings:​

  • When a derived database task is applied to an unencrypted database, it behaves similarly to a regular database backup task:

    • A snapshot will always be unencrypted.
    • A logical backup will comply with the configuration settings, and can be either unencrypted or encrypted using a user-provided key.

  • When a derived database task is applied to an encrypted database, its behavior may differ from that of a regular backup task, and the following rule applies:
    Both snapshots and logical backups are always encrypted using the database key.

    • If the encryption settings set by the server-wide configuration contradict this rule (e.g., providing a logical backup with a user-provided encryption key), they will be overridden and backups will still be encrypted using the database key.

    This behavior is by design, to ensure the safety of future databases joining the server-wide configuration.
    If you have an encrypted database, and you want its backups to be unencrypted or to be encrypted using a user-provided key, you can create a regular database backup task for this database and apply these options.

Learn to create and manage server-wide backup tasks using the client API
Learn to create and manage server-wide backup tasks via Studio

Backup on a sharded database​

On a sharded database, a single backup task is defined by the user for all shards, and RavenDB automatically defines sub-tasks that create backups per shard.

To restore a sharded database, paths to the individual shard backups are passed to the restore operation in their original order.
Shard backups can also be restored to non-sharded databases, either for a selective recovery of specific shards or for a complete restore.

  • The backup of a non-sharded database cannot be restored as a new sharded database.
  • The backup of a non-sharded database can, however, be imported into an existing sharded database.

Learn to create backups for a sharded database
Learn to restore shard backups

Monitoring backup tasks​

You can use SNMP endpoints to monitor your backup tasks and operations,
as well as retrieve information from a backup task using the API.

Backup SNMP endpoints​

RavenDB exposes SNMP endpoints for monitoring, including endpoints showing backups metrics.

ScopeOIDTypeDescription
Node1.13.1Integer32Number of backup operations currently running.
Node1.13.2Integer32Max number of backup operations that can run concurrently.
All cluster databases5.1.3TimeTicksTime elapsed since the oldest backup across all databases.
All cluster databases5.1.11.15Integer32Number of enabled backup tasks across all databases.
All cluster databases5.1.11.16Integer32Number of active backup tasks across all databases.

An active backup task is:
Enabled.
On a database that is loaded on this node.
On the node responsible for the task.

RavenDB's root OID is: 1.3.6.1.4.1.45751.1.1
e.g.,
To check the number of backup operations currently running on this node,
use the root OID + 1.13.1:
1.3.6.1.4.1.45751.1.1.1.13.1

Learn how to access RavenDB metrics via SNMP

Retrieving a backup task status​

You can retrieve a backup task's status, which reflects the task's most recent completed backup run (whether scheduled or triggered manually).

The retrieved status includes details such as the number of backups performed by the task and the lasy backup operation's timestamp, duration, destination path, and potentially error information.

Learn to retrieve the status of a database backup task
Learn to retrieve the status of a server-wide derived backup task

Restoring from backup​

When restoring from backup:

  • A new database is created.
  • The restore operation accesses the backup folder.
  • The full backup and all subsequent incremental backups are automatically retrieved and their content added to the new database in the correct order.

Learn how to restore a database from backup using the client API
Learn how to restore a database from backup via Studio

A database is typically restored from backup to a single node, and then replicated to the other cluster nodes.

When restored from a snapshot image, the database can be restored to multiple cluster nodes simultaneously. This is because snapshots retain document change vectors, allowing documents to be recognized across nodes without further replication.

Learn how to restore from backup to multiple cluster nodes

Recommended precautions​

Consider the following precautions to ensure the reliability and safety of your data.

Do not substitute the backup procedure with copying the database folder.​

The backup procedure addresses requirements that simply copying the database folder does not satisfy. For example:

  • A reliable point-in-time freeze ensures that the backup captures the database in a consistent state.
  • ACID compliance of the backed-up data, to ensure its integrity when restored.

Regularly remove old backup files.​

Define a retention policy to automatically remove outdated files and free up storage space.
When setting the retention period, consider how long backups should be retained to balance storage needs and recovery requirements.

Store backup files in a location other than your database's.​

If you save your backup files locally, verify they are not kept in the same directory as the database, to ensure there is enough storage space for both the backups and the database.

In this article