Skip to content

RDoc-3315 + RDoc-3929 server-wide snapshot backups + update unsupported features #2520

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Danielle9897 wants to merge 5 commits into
base: main
Choose a base branch
from
Open

RDoc-3315 + RDoc-3929 server-wide snapshot backups + update unsupported features #2520

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a76e5cb
RDoc-3315 Block server-wide snapshot backups for sharded databases
Danielle9897 Jun 18, 2026
b5d81a3
RDoc-3929 Sharding: update unsupported features
Danielle9897 Jun 18, 2026
0728869
RDoc-3315 fix links
Danielle9897 Jun 18, 2026
fe1e4cf
RDoc-3315 fix review comments
Danielle9897 Jun 22, 2026
ec48c0a
RDoc-3315 fix links
Danielle9897 Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 76 additions & 112 deletions docs/sharding/backup-and-restore/backup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Sharding: Backup"
description: "Back up RavenDB sharded databases with shard-aware backup tasks that capture data from all shards into coordinated backup sets."
sidebar_label: Backup
sidebar_label: "Backup"
sidebar_position: 0
---

Expand All @@ -14,31 +14,26 @@ import LanguageContent from "@site/src/components/LanguageContent";
import Panel from "@site/src/components/Panel";
import ContentFrame from "@site/src/components/ContentFrame";

# Sharding: Backup

<Admonition type="note" title="">

* Sharded databases are backed up using user-defined periodic
[backup tasks](../../backup/overview).
* Sharded databases are backed up using user-defined periodic [backup tasks](../../backup/overview).

* Shards can store backup files **locally** (each shard using its
own node machine storage) and/or **remotely** (all shards sending
backup files to a common remote destination like an AWS S3 bucket).
* Shards can store backup files **locally** (each shard using its own node machine storage)
and/or **remotely** (all shards sending backup files to a common remote destination like an AWS S3 bucket).

* Both [Full](../../backup/overview#full-backup)
and [Incremental](../../backup/overview#incremental-backup)
* Both [Full](../../backup/overview.mdx#full-backup) and [Incremental](../../backup/overview#incremental-backup)
backups can be created for a sharded database.

* A [logical](../../backup/overview#logical-backup) backup **can** be:
* A [logical](../../backup/overview.mdx#logical-backup) backup **can** be:
- Created for a sharded database.
- Restored into either a sharded or a non-sharded database.

* A [snapshot](../../backup/overview#snapshot-image)
**cannot** be created for a sharded database.
* A [snapshot](../../backup/overview.mdx#snapshot-image) **cannot** be created for a sharded database
(and sharded databases are automatically excluded from server-wide **snapshot** backups).

* A [one-time](../../backup/create/one-time-backup) backup **can** be created for a sharded database.
* A [one-time](../../backup/create/one-time-backup.mdx) backup **can** be created for a sharded database.

* In this page:
* In this article:
* [Sharded and non-sharded backup tasks](../../sharding/backup-and-restore/backup.mdx#sharded-and-non-sharded-backup-tasks)
* [Backup storage: local and remote](../../sharding/backup-and-restore/backup.mdx#backup-storage-local-and-remote)
* [Backup files extension and structure](../../sharding/backup-and-restore/backup.mdx#backup-files-extension-and-structure)
Expand All @@ -53,48 +48,33 @@ import ContentFrame from "@site/src/components/ContentFrame";

<Panel heading="Sharded and non-sharded backup tasks">

From a user's perspective, backing up a sharded database is done by
defining and running **a single backup task**, just like it is done
with a non-sharded database.
From a user's perspective, backing up a sharded database is done by defining and running **a single backup task**,
just like it is done with a non-sharded database.

Behind the scenes, though, each shard backs up its own slice of the
database independently from other shards.
Behind the scenes, though, each shard backs up its own slice of the database independently of other shards.

Distributing the backup responsibility between the shards allows
RavenDB to speed up the backup process and keep backup files in
manageable proportions no matter what the overall database size is.
Distributing the backup responsibility between the shards allows RavenDB to speed up the backup process
and keep backup files in manageable proportions no matter what the overall database size is.

### Non-sharded DB backup tasks

* A complete replica of the database is kept by each cluster node.
* Any node can therefore be made
[responsible](../../server/clustering/distribution/highly-available-tasks.mdx#responsible-node)
for backups by the cluster.
* The responsible node runs the backup task periodically to create
a backup of the entire database.
* Any node can therefore be made [responsible](../../server/clustering/distribution/highly-available-tasks.mdx#responsible-node) for backups by the cluster.
* The responsible node runs the backup task periodically to create a backup of the entire database.

### Sharded DB backup tasks

* Each shard hosts a unique part of the database, so no single node
can create a backup of the entire database.
* After a user defines a backup task, RavenDB automatically creates
one backup task per shard, based on the user-defined task.
This operation is automatic and requires no additional actions
from the user.
* Each shard appoints [one of its nodes](../../sharding/overview.mdx#shard-replication)
responsible for the execution of the shard's backup task.
* Each shard backup task can keep the shard's database
locally (on the shard machine), and/or remotely (on one
or more cloud destinations).
* A backup task can store backups on multiple destinations,
e.g., locally, on an S3 bucket, and on an Azure blob.
* To [restore](../../sharding/backup-and-restore/restore.mdx)
the entire database, the restore operation is provided with
the locations of the backup folders used by all shards.
* When restoring the database, the user doesn't have to restore
all shard backups. It is possible, for example, to restore only
one of the shards. Using this flexibility, a sharded database
can easily be split into several databases.
* Each shard hosts a unique part of the database, so no single node can create a backup of the entire database.
* After a user defines a backup task, RavenDB automatically creates one backup task per shard, based on the user-defined task.
This operation is automatic and requires no additional actions from the user.
* Each shard appoints [one of its nodes](../../sharding/overview.mdx#shard-replication) responsible for the execution of the shard's backup task.
* Each shard backup task can keep the shard's database locally (on the shard machine),
and/or remotely (on one or more cloud destinations).
* A backup task can store backups on multiple destinations, e.g., locally, on an S3 bucket, and on an Azure blob.
* To [restore](../../sharding/backup-and-restore/restore.mdx) the entire database,
the restore operation is provided with the locations of the backup folders used by all shards.
* When restoring the database, the user doesn't have to restore all shard backups.
It is possible, for example, to restore only one of the shards. Using this flexibility, a sharded database can easily be split into several databases.

</Panel>

Expand All @@ -104,114 +84,94 @@ Backup files can be stored locally and remotely.
Find a code example [here](../../sharding/backup-and-restore/backup.mdx#example).

* **Local backup**
A shard's backup task may keep backup data locally,
using the node's local storage.
A shard's backup task may keep backup data locally, using the node's local storage.

[Restoring](../../sharding/backup-and-restore/restore.mdx#section-2)
backup files that were stored locally requires the user to provide
the restore operation with the location of the backup folder on each
shard's node.
[Restoring](../../sharding/backup-and-restore/restore.mdx#section-2) backup files that were stored locally
requires the user to provide the restore operation with the location of the backup folder on each shard's node.

* **Remote location**
Backups can also be kept remotely. All shards will transfer
the backup files to a common location, using one of the currently
supported platforms:
Backups can also be kept remotely.
All shards will transfer the backup files to a common location, using one of the currently supported platforms:
* An FTP/SFTP target
* Azure Storage
* Amazon S3
* Amazon Glacier
* Google Cloud

[Restoring](../../sharding/backup-and-restore/restore.mdx#section-2)
backup files that were stored remotely requires the user to provide
the restore operation with each shard's backup folder location.
[Restoring](../../sharding/backup-and-restore/restore.mdx#section-2) backup files that were stored remotely
requires the user to provide the restore operation with each shard's backup folder location.

</Panel>

<Panel heading="Backup files extension and structure">

Backup files use the same internal structure as the `.ravendbdump`
files that [Studio](../../studio/database/tasks/export-database.mdx)
and [Smuggler](../../client-api/smuggler/what-is-smuggler.mdx)
create when **exporting** data.
Backup files use the same internal structure as the `.ravendbdump` files that [Studio](../../studio/database/tasks/export-database.mdx)
and [Smuggler](../../client-api/smuggler/what-is-smuggler.mdx) create when **exporting** data.
It is therefore possible to not only [restore](../../sharding/backup-and-restore/restore.mdx)
but also **import** backup files using [studio](../../studio/database/tasks/import-data/import-data-file.mdx)
and [smuggler](../../client-api/smuggler/what-is-smuggler.mdx#import).
but also **import** backup files using [studio](../../studio/database/tasks/import-data/import-data-file.mdx) and [smuggler](../../client-api/smuggler/what-is-smuggler.mdx#import).
Read more about this feature [here](../../sharding/import-and-export.mdx#import).


<Admonition type="note" title="">

Backed-up data includes both
[database-level and cluster-level content](../../backup/overview#backup-content).
Backed-up data includes both [database-level and cluster-level content](../../backup/overview#backup-content).
</Admonition>

</Panel>

<Panel heading="Backup type">

A shard backup task can create a
[Logical backup](../../backup/overview#logical-backup)
only.
A backup task for a sharded database can create a [logical backup](../../backup/overview.mdx#logical-backup) only.

A [Snapshot](../../backup/overview#snapshot-image)
backup **cannot** be created for a sharded database.
A [Snapshot](../../backup/overview#snapshot-image) backup **cannot** be created for a sharded database.

`Logical` backups created for a sharded database can be restored into
both sharded and non-sharded databases.
`Logical` backups created for a sharded database can be restored into both sharded and non-sharded databases.

</Panel>

<Panel heading="Backup scope">

A shard backup task can create
a [Full backup](../../backup/overview#full-backup)
with the entire content of the shard, or an
[Incremental Backup](../../backup/overview#incremental-backup)
with just the difference between the current database data and the last backed-up data.
A backup task for a sharded database can create a [full backup](../../backup/overview.mdx#full-backup) with the entire content of each shard,
or an [incremental backup](../../backup/overview#incremental-backup) with just the difference between the current data and the last backed-up data.

</Panel>

<Panel heading="Naming convention">

* Backup files created for a sharded database generally follow the same [naming
convention](../../backup/overview#naming-and-folder-structure)
as non-sharded database backups.
* Backup files created for a sharded database generally follow the same [naming convention](../../backup/overview#naming-and-folder-structure) as non-sharded database backups.

* Each shard keeps its backup files in a folder whose name consists of:
* **Date and Time** (when the folder was created)
* **Database Name**
* `$` symbol
* **Shard Number**

The backup folders for a 3-shard database named "Books",
for example, can be named:
The backup folders for a 3-shard database named "Books", for example, can be named:
`2023-02-05-16-17.Books$0` for shard 0
`2023-02-05-16-17.Books$1` for shard 1
`2023-02-05-16-17.Books$2` for shard 2

</Panel>

<Panel heading="Server-wide backup">

[Server-wide backup](../../backup/overview#server-wide-backup)
backs up all the databases hosted by the cluster, by creating a backup
task for each database and executing all tasks at a scheduled time.

* A server-wide backup will create backups for both non-sharded **and**
sharded databases.
* To create a backup for an entire sharded database, the operation will
define and execute a backup task for each shard, behaving as if it was
defined manually.

[Server-wide backup](../../backup/overview#server-wide-backup) creates and runs the required backup tasks
for the databases hosted by the cluster at the scheduled time.

* A server-wide **logical** backup creates backups for both non-sharded and sharded databases.
For a sharded database, RavenDB defines and executes a backup task for each shard,
as if the task was defined manually.

* A server-wide **snapshot** backup excludes sharded databases, since snapshots cannot be created for sharded databases.
RavenDB automatically adds sharded database names to the server-wide snapshot task's `ExcludedDatabases` list,
including sharded databases created after the task already exists.

</Panel>

<Panel heading="Example">

The backup task that we define here is similar to the task we
would define for a non-sharded database. As part of a sharded
database, however, this task will be re-defined automatically
by the orchestrator for each shard.
The backup task that we define here is similar to the task we would define for a non-sharded database.
As part of a sharded database, however, this task will be re-defined automatically by the orchestrator for each shard.

```csharp
var config = new PeriodicBackupConfiguration
Expand Down Expand Up @@ -251,28 +211,32 @@ var config = new PeriodicBackupConfiguration
var operation = new UpdatePeriodicBackupOperation(config);
var result = await store.Maintenance.SendAsync(operation);
```
<br/>

<Admonition type="warning" title="Casting Backup Results" id="casting-backup-results" href="#casting-backup-results">
<Admonition type="warning" title="">

#### Casting Backup Results

In a sharded database, results are returned by Backup in a `ShardedBackupResult` type.
This type is specific to a sharded database, and casting it using a non-sharded type
[will fail](../../migration/client-api/previous-versions-client-breaking-changes#casting-smuggler-results).
This type is specific to a sharded database, and casting it using a non-sharded type [will fail](../../migration/client-api/previous-versions-client-breaking-changes#casting-smuggler-results).
</Admonition>

</Panel>

<Panel heading="Backup Options Summary">

| Option | Available on a Sharded Database | Comment |
| -------------------- | --------------- | --------------------- |
| Store backup files created by shards in **local shard machine storage** | **Yes** | Shards can store the backups they create locally. |
| ------ | ------------------------------- | ------- |
| Store backup files created by shards in **local shard machine storage** | **Yes** | Shards can store the backups they create locally. |
| Store backup files of sharded databases [remotely](../../sharding/backup-and-restore/backup.mdx#backup-storage-local-and-remote) | **Yes** | Shards can store the backups they create on remote S3, Azure, or Google Cloud destinations. |
| Create [Full](../../backup/overview#full-backup) backups for sharded databases | **Yes** | |
| Create [Incremental](../../backup/overview#incremental-backup) backups for sharded databases | **Yes** | |
| Create [Logical](../../backup/overview#logical-backup) backups for sharded databases | **Yes** | |
| Create [Snapshot](../../backup/overview#snapshot-image) backups for sharded databases | **No** | Snapshot backups CANNOT be created for (nor restored to) sharded databases. |
| Create **periodic backup tasks** for sharded databases | **Yes** | |
| Run a manual [one-time](../../backup/create/one-time-backup) backup operation on a sharded database | **Yes** | |
| Include sharded databases in a [server-wide backup operation](../../sharding/backup-and-restore/backup.mdx#server-wide-backup) | **Yes** | A server-wide backup operation will create backups for all databases, including the sharded ones. |
| Create [Full](../../backup/overview#full-backup) backups for sharded databases | **Yes** | |
| Create [Incremental](../../backup/overview#incremental-backup) backups for sharded databases | **Yes** | |
| Create [Logical](../../backup/overview#logical-backup) backups for sharded databases | **Yes** | |
| Create [Snapshot](../../backup/overview#snapshot-image) backups for sharded databases | **No** | Snapshot backups CANNOT be created for (nor restored to) sharded databases. |
| Create **periodic backup tasks** for sharded databases | **Yes** | |
| Run a manual [one-time](../../backup/create/one-time-backup) backup operation on a sharded database | **Yes** | |
| Include sharded databases in a [server-wide backup operation](../../sharding/backup-and-restore/backup.mdx#server-wide-backup) | **Yes (logical only)** | A server-wide **logical** backup includes all databases, including sharded ones. Sharded databases are automatically **excluded** from server-wide **snapshot** backups. |

</Panel>

Loading