Skip to content

Latest commit

 

History

History
312 lines (229 loc) · 13.4 KB

backup.markdown

File metadata and controls

312 lines (229 loc) · 13.4 KB
Raw

Backup

{NOTE: }

{NOTE/}

{PANEL: Backup Types}

####Logical-Backup

  • Data is backed-up in compressed JSON files.

  • During the restoration, RavenDB -

    • Re-inserts all data into the database.
    • Inserts the saved index definitions. To save space, Logical Backup stores index definitions only.
      After restoration, the dataset is scanned and indexed according to the definitions.

  • Restoration time is, therefore, slower than when restoring from a Snapshot.

  • The backup file size is significantly smaller than that of a Snapshot.

  • In addition to full data backup, Logical Backups can be defined as incremental, saving any changes made since the previous backup.

  • The following code sample defines a full-backup task that would be executed every 3 hours:
    {CODE logical_full_backup_every_3_hours@ClientApi\Operations\Maintenance\Backup\Backup.cs /} Note the usage of Cron scheduling when setting backup frequency.

####Snapshot

  • A Snapshot is a compressed binary duplication of the full database structure. This includes the data file and the journals at a given point in time.
    Therefore it includes fully built indexes and ongoing tasks.
    See file structure for more info.

  • Snapshot backups are available only for Enterprise subscribers.

  • During restoration -

    • Re-inserting data into the database is not required.
    • Re-indexing is not required.

  • Restoration is typically faster than that of a logical backup.

  • Snapshot size is typically larger than that of a logical backup.

  • If Incremental backups are created for a Snapshot-type backup:

    • The first backup will be a full Snapshot.
    • The following backups will be Incremental.
    • Incremental backups have different storage contents than Snapshots.

  • Code Sample:
    {CODE backup_type_snapshot@ClientApi\Operations\Maintenance\Backup\Backup.cs /}

####Basic Comparison Between a Logical-Backup and a Snapshot:

| Backup Type | Stored Format | Restoration speed | Size | ------ | ------ | ------ | | Snapshot | Compressed Binary Image | Fast | Larger than a logical-backup | Logical backup | Compressed Textual Data - JSON | Slow | Smaller than a Snapshot

{NOTE: Make sure your server has access to the local backup path.} Verify that RavenDB is allowed to store files in the path set in LocalSettings.FolderPath. {NOTE/}

{PANEL/}

{PANEL: Backup Scope}

As described in the overview, a backup task can create full and incremental backups.

  • A Backup Task can be defined to create either a full data backup or an incremental backup.
    In both cases, the backup task adds a single new backup file to the backup folder each time it runs, leaving the existing backup files untouched.

####Full-Backup

  • File Format
    A full-backup is a compressed JSON file if it is a logical backup, or a compressed binary file if it is a snapshot.

  • Task Ownership
    There are no preliminary conditions for creating a full-backup. Any node can perform this task.

  • To run a full-backup
    Set FullBackupFrequency. {CODE backup_full_backup@ClientApi\Operations\Maintenance\Backup\Backup.cs /}

####Incremental-Backup

  • File Format and Notes About Contents

    • An incremental-backup file is always in JSON format. It is so even when the full-backup it is associated with is a binary snapshot.
    • An incremental backup stores index definitions (not full indexes).
      After the backup is restored, the dataset is re-indexed according to the index definitions. {NOTE: } This initial re-indexing can be time-consuming on large datasets. {NOTE/}
    • An incremental backup doesn't store change vectors.

  • 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 full-backup at least once.

  • To run an incremental-backup
    Set IncrementalBackupFrequency. {CODE backup_incremental_backup@ClientApi\Operations\Maintenance\Backup\Backup.cs /}

{PANEL/}

{PANEL: Backup to Local and Remote Destinations}

  • Backups can be made locally, as well as to a set of remote locations including -

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

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

  • Local and Remote Destinations Settings Code Sample:
    {CODE backup_remote_destinations@ClientApi\Operations\Maintenance\Backup\Backup.cs /}

{INFO: Tip} Use AWS IAM (Identity and Access Management) to restrict users access while they create backups.
E.g. -
{CODE-BLOCK:json} { "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" } ] } {CODE-BLOCK/} {INFO/} {PANEL/}

{PANEL: Backup Retention Policy}

By default, backups are stored indefinitely. 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.

Full backups and their corresponding incremental backups are deleted together. Before a full backup can be deleted, all of its incremental backups must be older than the retention period as well.

The retention policy is a property of PeriodicBackupConfiguration:

{CODE-BLOCK:csharp } public class RetentionPolicy { public bool Disabled { get; set; } public TimeSpan? MinimumBackupAgeToKeep { get; set; } } {CODE-BLOCK/}

Parameter Type Description
Disabled bool If set to true, backups will be retained indefinitely, and not deleted. Default: false
MinimumBackupAgeToKeep TimeSpan The minimum amount of time to retain a backup. Once a backup is older than this time span, it will be deleted during the next scheduled backup task.

Example

{CODE:csharp backup_retentionpolicy@ClientApi\Operations\Maintenance\Backup\Backup.cs /}

{PANEL/}

{PANEL: Server-Wide Backup}

You can create a Server-Wide Backup task to back-up all the databases in your cluster at a scheduled time.

  • Backups can be made locally, as well as to a set of remote locations.

  • Server-wide Backup Code Sample: {CODE server_wide_backup_configuration@ClientApi\Operations\Maintenance\Backup\ServerWideBackup.cs /}

{PANEL/}

{PANEL: Initiate Immediate Backup Execution}

The Backup task is executed periodically on its predefined schedule.
If needed, it can also be executed immediately.

  • To execute an existing backup task immediately, use the StartBackupOperation method.
    {CODE initiate_immediate_backup_execution@ClientApi\Operations\Maintenance\Backup\Backup.cs /}

    • Definition: {CODE start_backup_operation@ClientApi\Operations\Maintenance\Backup\Backup.cs /}

    • Parameters:

      | Parameter | Type | Functionality |
| ------ | ------ | ------ |
| isFullBackup | bool | true: full-backup <br> false: incremental-backup |
| taskId |  long | The existing backup task ID |

  • To verify the execution results, use the GetPeriodicBackupStatusOperation method.
    {CODE get_backup_execution_results@ClientApi\Operations\Maintenance\Backup\Backup.cs /}

    • Return Value:
      The PeriodicBackupStatus object returned from GetPeriodicBackupStatusOperation is filled with the previously configured backup parameters and with the execution results.
      {CODE periodic_backup_status@ClientApi\Operations\Maintenance\Backup\Backup.cs /} {PANEL/}

{PANEL: Recommended Precautions} {WARNING: }

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

  • Remove old backup files regularly.
    Set the backup retention policy to remove unneeded backup files so that they don't build up.
    While setting how many days to keep your backups, consider how much of a recent database history you would like to have access to.

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

{WARNING/} {PANEL/}

Related Articles

###Server

###Client API

###Studio

###Security

###Migration