{NOTE: }
-
A sharded database's backup is a set of backup files that were created by the database's shards.
-
To restore a sharded database, we need to pass the restore operation paths to the locations of the backup files so it can retrieve and restore them.
{WARNING: } Shards must be restored in their original order.
The backup of shard 1, for example, must be restored as shard 1. {WARNING/} -
Backup files can be restored from local shard node storage or from a remote location.
-
A backed-up sharded database can be restored in part or in full, to a sharded or a non-sharded database.
-
Only logical backups are supported. Snapshot backups cannot be created or restored for sharded databases.
-
.ravendbdump
files (exported from RavenDB databases) and backup files can also be imported into a database (sharded or non-sharded). -
A backup created for a non-sharded database cannot be restored as a sharded database.
-
In this page:
{NOTE/}
{PANEL: Restore}
To restore a sharded database, we need to:
When a shard stores a backup file, it may store it locally (on the shard node's storage) or remotely (supported platforms currently include S3 Buckets, Azure Blobs, and Google cloud).
To restore the backup files, we need to provide the restore process with
each shard's backup folder location.
The shards' backup folder locations, and additional data regarding the backups,
are provided in a dictionary of SingleShardRestoreSetting
objects.
SingleShardRestoreSetting
{CODE restore_SingleShardRestoreSetting@Sharding\ShardingBackupAndRestore.cs /}
-
Parameters:
Parameter Value Functionality ShardNumber int
The shard number that will be given to the restored shard.
should normally be similar to the original shard number.NodeTag string
The node to restore the shard on. FolderName string
The name of the folder that holds the backup file/s. LastFileNameToRestore string
Last incremental backup file to restore.
If omitted, restore all backup files in folder.{WARNING: } When setting ShardNumber, please make sure that all shards are given the same numbers they had when they were backed-up.
Giving a restored shard a number different than its original number will place buckets on the wrong shards and cause mapping errors.E.g., a backup of shard 1 must be restored as shard 1:
ShardNumber = 1
{WARNING/}{WARNING: } When restoring a local shard backup, make sure that the backup file resides on the node that the shard's
NodeTag
property is set to, so the restore process can find the file.E.g., if a backup file that's been produced by node
A
is now restored to nodeB
(NodeTag = "B"
), place the backup file in the backup folder of nodeB
before initiating the restore operation.
{WARNING/}
To restore the database, we pass the Restore Operation a configuration object.
-
The configuration object inherits properties from the
RestoreBackupConfigurationBase
class (discussed below) and defines additional sharding-specific settings. -
We choose what configuration object to pass the restore operation, by the backup files' location.
The backup files may be located locally (on each shard machine storage) or remotely (in a cloud location).Configuration Object Backup Location Additional Properties RestoreBackupConfiguration
Local shard storage None (see example) RestoreFromS3Configuration
AWS S3 Bucket S3Settings
(see S3 example)RestoreFromAzureConfiguration
MS Azure Blob AzureSettings
(see Azure example)RestoreFromGoogleCloudConfiguration
Google Cloud Bucket GoogleCloudSettings
(see Google Cloud example)
RestoreBackupConfigurationBase
is a parent class to all the configuration types
mentioned above, allowing you to set backups encryption settings among other options.
{CODE restore_RestoreBackupConfigurationBase@Sharding\ShardingBackupAndRestore.cs /}
-
Parameters:
Parameter Value Functionality DatabaseName string
Name for the new database. LastFileNameToRestore
(Optional -
omit for default)string
Last incremental backup file to restore.
Ignored when restoring a sharded database.
SingleShardRestoreSetting.LastFileNameToRestore
used instead, per shard.DataDirectory
(Optional -
omit for default)string
The new database data directory.
Default folder:
Under the "Databases" folder
In a folder carrying the restored database name.EncryptionKey
(Optional -
omit for default)string
A key for an encrypted database.
Default behavior:
Try restoring as if DB is unencrypted.DisableOngoingTasks
(Optional -
omit for default)boolean
true
- disable ongoing tasks when Restore is complete.
false
- enable ongoing tasks when Restore is complete.
Default:false
Ongoing tasks will run when Restore is complete.SkipIndexes
(Optional -
omit for default)boolean
true
- disable indexes import,
false
- enable indexes import.
Default:false
Restore all indexes.ShardRestoreSettings ShardedRestoreSettings
a dictionary of SingleShardRestoreSetting
instances defining paths to backup locations
{CODE restore_ShardedRestoreSettings@Sharding\ShardingBackupAndRestore.cs /}BackupEncryptionSettings BackupEncryptionSettings
Backup Encryption Settings {NOTE: } Verify that RavenDB has full access to the backup locations and database files.
Make sure your server has write permission toDataDirectory
.
{NOTE/}
Pass the configuration object you defined to the RestoreBackupOperation
store operation
to restore the database.
{CODE restore_RestoreBackupOperation@Sharding\ShardingBackupAndRestore.cs /}
- Instead of
RestoreBackupConfigurationBase
, use the configuration object you prepared:RestoreBackupConfiguration
for locally-stored backupsRestoreFromS3Configuration
to restore from S3RestoreFromAzureConfiguration
to restore from AzureRestoreFromGoogleCloudConfiguration
to restore from Google Cloud
Here are examples for restoring a sharded database using backup files stored locally and remotely.
{CODE-TABS} {CODE-TAB:csharp:Local_Storage restore_local-settings@Sharding\ShardingBackupAndRestore.cs /} {CODE-TAB:csharp:S3_Bucket restore_s3-settings@Sharding\ShardingBackupAndRestore.cs /} {CODE-TAB:csharp:Azure_Blob restore_azure-settings@Sharding\ShardingBackupAndRestore.cs /} {CODE-TAB:csharp:Google_Cloud restore_google-cloud-settings@Sharding\ShardingBackupAndRestore.cs /} {CODE-TABS/}
{PANEL/}
{PANEL: Restoring to a Selected Restore Point}
When a full backup is created, (for either a non sharded database or for
any shard of a sharded database), a backup folder is created to contain it.
When incremental backups are created, they are stored in the folder of
the last full backup.
To restore a backup, its folder name is provided. By default, the full
backup stored in this folder will be restored, as well as all the incremental
backups that were added to it over time.
- Read here about restoring a non-sharded database.
- In short, restoring a non-sharded database to a selected restore point
is done by filling:
- RestoreBackupConfiguration.BackupLocation with the backup location.
- RestoreBackupConfiguration.LastFileNameToRestore with the name of the last incremental backup to restore.
-
When a sharded database is restored,
RestoreBackupConfiguration.BackupLocation
andRestoreBackupConfiguration.LastFileNameToRestore
mentioned above are overridden by per-shard settings. -
To restore the database of a particular shard up to a selected restore point simply add
ShardRestoreSettings.SingleShardRestoreSetting.LastFileNameToRestore
to the shard configuration and fill it with the name of the last incremental backup to restore. -
Example:
{CODE-TABS} {CODE-TAB:csharp:Local_Storage singleShardSettings_restore_local-settings@Sharding\ShardingBackupAndRestore.cs /} {CODE-TAB:csharp:S3_Bucket singleShardSettings_restore_s3-settings@Sharding\ShardingBackupAndRestore.cs /} {CODE-TAB:csharp:Azure_Blob singleShardSettings_restore_azure-settings@Sharding\ShardingBackupAndRestore.cs /} {CODE-TAB:csharp:Google_Cloud singleShardSettings_restore_google-cloud-settings@Sharding\ShardingBackupAndRestore.cs /} {CODE-TABS/}
{PANEL/}
{PANEL: Restore Options Summary}
Option | Supported on a Sharded Database | Comment |
---|---|---|
Restore from local shard storage | Yes | |
Restore from a remote location | Yes | Define a restore configuration with S3, Azure, or Google Cloud settings. |
Restore a sharded database backup to a sharded database |
Yes | |
Restore a sharded database backup to a non-sharded database |
Yes | |
Restore a non-sharded database backup to a sharded database |
No | A backup created for a non-sharded database CANNOT be restored to a sharded database. |
Restore a Full database backup | Yes | |
Restore a Partial database backup | Yes | |
Restore a Logical database backup | Yes | |
Restore a Snapshot database backup | No | A snapshot backup CANNOT be restored by a sharded database. |
Restore backed-up shards in a different order than the original | No | Always restore the shards in their original order. |
{PANEL/}