Backup Overview


  • Maintaining a proper backup routine ensures that you'd be able to restore your data to its state at chosen points in time. Use this overview as an introduction to backing up and restoring your databases.

  • The two principal reasons for backing up your database are -

    • Securing data in case catastrophe strikes.
    • Freezing data in chosen points in time to retain access to it in various stages of its existence/development.
  • RavenDB's Backup is an Ongoing task.

    • Routinely backing up your data is a fundamental aspect of your database maintenance.
      Backup is therefore provided not as a one-time operation, but as an ongoing task that runs in the background.
      It is configured once and then executed periodically according to the defined schedule.
  • You can create and configure backup tasks using the Client API or in Studio navigate from Tasks -> Backups -> Create a Periodic Backup.

  • In this page:


Backup Type

There are two backup types: Logical-backup (or simply "Backup") and Snapshot.

Logical Backup

A logical backup is a compressed JSON dump of database contents, including documents, index definitions, and additional data that can be stored in full and incremental backups.

  • After a database restore, the dataset is re-indexed by the backed-up index definitions.
    This can be time-consuming in large datasets.

Snapshot

A snapshot is a binary image of the database contents, full indexes, and additional data at a given point in time.

  • Restoration time is reduced because no re-indexing is needed, but more data is transferred during backups.
  • Incremental Snapshot backups (the changes made since the last backup) do not incrementally update indexes or change vector data after the initial complete Snapshot image.

    Snapshots are only available for Enterprise subscribers.

Backup Contents

Backed-up data includes both database-level and cluster-level contents, as detailed below.

Database-level data Logical Backup Snapshot
Documents & Revisions
Attachments
Counters
Time-Series
Change Vector data Change Vectors are not preserved, thus recreated from the beginning upon restore
Tombstones
Conflicts
Cluster-level data Logical Backup Snapshot
Database Record
Compare-exchange values
Identities
Indexes Index definitions are saved and used to rebuild indexes during database restoration
Ongoing Tasks configuration
Subscriptions

Backup Scope: Full or Incremental

You can set the Backup task to create either full or incremental backups during its periodical executions.

Full Backup

A full backup contains all current database contents and configuration.

  • The creation of a full-backup file normally takes longer and requires more storage space than the creation of an incremental-backup file.

Incremental Backup

An incremental backup contains only the difference between the current database data and the last backed-up data.

  • An incremental-backup file is normally faster to create and smaller than a full-backup file.
  • When an incremental-backup task is executed, it checks for the existence of a previous backup file.
    If such a file doesn't exist, the first backup created will be a full backup.
    Subsequent backups will be incremental.

  • A Typical Configuration
    A typical configuration would include quick incremental-backup runs that "fill the gaps" between full backups.

  • For example -
    A full-backup task is set to run every 12 hours,
    and an incremental-backup task that runs every 30 minutes.

Backup Name and Folder Structure

Naming

Backup folders and files are named automatically.

  • Their names are constructed of:
    Current Date and Time
    Backed-up Database Name
    Owner-Node Tag
    Backup Type ("backup" or "snapshot")
    Backup Scope ("full-backup" or "incremental-backup")

  • For example:

    • 2018-12-26-16-17.ravendb-Products-A-backup is the name automatically given to a backup folder.
      • "2018-12-26-16-17" - Backup Date and time
      • "Products" - Backed-up Database name
      • "A" - Executing node's tag
      • "backup" - Backup type (backup/snapshot)
    • 2018-12-26-16-17.ravendb-full-backup is the name automatically given to the backup file inside this folder.
      • "full-backup" - For a full backup; an incremental backup's name will state "incremental-backup".

Folder Structure

A typical backup folder holds a single full-backup file and a list of incremental-backup files that supplement it.
Each incremental backup file contains only the delta from its predecessor backup file.

  • 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

Stored backup data can be Encrypted or Unencrypted.

Compression

  • A backup always consists of a single compressed file.
    It is so for all backup formats: Full "logical" backup dumps, Snapshot images, and the Incremental backups that supplement both.
  • Data is compressed using gzip.

Retention Policy

By default, backups are not deleted. The backup retention policy sets a retention period, at the end of which backups are deleted. Deletion occurs during the next scheduled backup task after the end of the retention period.

Restoration Procedure

In order to restore a database -

  • Provide RavenDB with the backup folder's path.
  • To restore an encrypted database, you must provide the encryption key.
  • RavenDB will browse this folder and restore the full-backup found in it.
  • RavenDB will then restore the incremental-backups one by one, up to and including the last one. You can set LastFileNameToRestore to stop restoration at a specific backup file.