---
title: "Sharding: Backup"
description: "* Sharded databases are backed up using user-defined periodic"
url: "https://docs.ravendb.net/6.2/sharding/backup-and-restore/backup"
version: "6.2"
---

# Sharding: Backup

> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

## Sharding: Backup

> **Note**
>
> - Sharded databases are backed up using user-defined periodic
>   [backup tasks](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md).
>
> - 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](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#full-backup)
>   and [Incremental](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#incremental-backup)
>   backups can be created for a sharded database.
>
> - A [logical](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#logical-backup)
>   backup **can** be created for a sharded database and restored into either
>   a sharded or a non-sharded database.
>
> - A [snapshot](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#snapshot) **cannot** be created for a sharded database  
>   (and sharded databases are automatically excluded from server-wide **snapshot** backups).
>
> - A manual [one-time](https://docs.ravendb.net/6.2/studio/database/tasks/backup-task.md#manually-creating-one-time-backups)
>   backup **can** be created for a sharded database.
>
> - In this page:
>   - [Backup](#backup)
>     - [Sharded and Non-Sharded Backup Tasks](#sharded-and-non-sharded-backup-tasks)
>     - [Backup Storage: Local and Remote](#backup-storage-local-and-remote)
>     - [Backup Files Extension and Structure](#backup-files-extension-and-structure)
>     - [Backup Type](#backup-type)
>     - [Backup Scope](#backup-scope)
>     - [Naming Convention](#naming-convention)
>     - [Server-Wide Backup](#server-wide-backup)
>     - [Example](#example)
>   - [Backup Options Summary](#backup-options-summary)

## Backup

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

Behind the scenes, though, each shard backs up its own slice of the
database independently from 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.

### Non-Sharded DB Backup Tasks

- A complete replica of the database is kept by each cluster node.
- Any node can therefore be made
  [responsible](https://docs.ravendb.net/6.2/server/clustering/distribution/highly-available-tasks.md#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](https://docs.ravendb.net/6.2/sharding/overview.md#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](https://docs.ravendb.net/6.2/sharding/backup-and-restore/restore.md)
  the entire database, the restore process 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.

## Backup Storage: Local and Remote

Backup files can be stored locally and remotely.  
Find a code example [here](#example).

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

  [Restoring](https://docs.ravendb.net/6.2/sharding/backup-and-restore/restore.md#section-2)
  backup files that were stored locally requires the user to provide
  the restore process 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:

  - Azure Blob Storage
  - Amazon S3 Storage
  - Google Cloud Platform

  [Restoring](https://docs.ravendb.net/6.2/sharding/backup-and-restore/restore.md#section-2)
  backup files that were stored remotely requires the user to provide
  the restore process with each shard's backup folder location.

## Backup Files Extension and Structure

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

> **Note**
>
> Backed-up data includes both
> [database-level and cluster-level content](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#backup-contents).

## Backup Type

A backup task for a sharded database can create a [logical backup](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#logical-backup) only.

A [Snapshot](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#snapshot) 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.

## Backup Scope

A backup task for a sharded database can create a [full backup](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#full-backup) with the entire content of each shard,  
or an [incremental backup](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#incremental-backup) with just the difference between the current data and the last backed-up data.

## Naming Convention

- Backup files created for a sharded database generally follow the same naming
  [convention](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#backup-name-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:  
    `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

## Server-Wide Backup

[Server-wide backup](https://docs.ravendb.net/6.2/studio/server/server-wide-backup.md) 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.

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

```csharp
var config = new PeriodicBackupConfiguration
{
  LocalSettings = new LocalSettings
  {
      FolderPath = @"E:/RavenBackups"
  },

  //Azure Backup settings
  AzureSettings = new AzureSettings
  {
      StorageContainer = "storageContainer",
      RemoteFolderName = "remoteFolder",
      AccountName = "JohnAccount",
      AccountKey = "key"
  },

  //Amazon S3 bucket settings
  S3Settings = new S3Settings
  {
      AwsAccessKey = "your access key here",
      AwsSecretKey = "your secret key here",
      AwsRegionName = "OPTIONAL",
      BucketName = "john-bucket"
  },

  // Google Cloud bucket settings
  GoogleCloudSettings = new GoogleCloudSettings
  {
      BucketName = "your bucket name here",
      RemoteFolderName = "remoteFolder",
      GoogleCredentialsJson = "your credentials here"
  }
};

var operation = new UpdatePeriodicBackupOperation(config);
var result = await docStore.Maintenance.SendAsync(operation);
```

> **Warning:** Casting Backup Results {#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](https://docs.ravendb.net/6.2/migration/client-api/client-breaking-changes.md#casting-smuggler-results).

## 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 of sharded databases [remotely](#backup-storage-local-and-remote) | **Yes** | Shards can store the backups they create on remote S3, Azure, or Google Cloud destinations. |
| Create [Full](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#full-backup) backups for sharded databases | **Yes** | |
| Create [Incremental](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#incremental-backup) backups for sharded databases | **Yes** | |
| Create [Logical](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#logical-backup) backups for sharded databases | **Yes** | |
| Create [Snapshot](https://docs.ravendb.net/6.2/server/ongoing-tasks/backup-overview.md#snapshot) 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](https://docs.ravendb.net/6.2/studio/database/tasks/backup-task.md#manually-creating-one-time-backups) backup operation on a sharded database | **Yes** | |
| Include sharded databases in a [server-wide backup operation](#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. |
