Skip to main content

Periodic server-wide backup tasks

Overview​

A server-wide backup task is a backup configuration template that is automatically applied to all your databases as per-database backup tasks.

  • An individual database backup task will also be automatically added to any database created after defining a server-wide backup task.
  • When creating the task, you can exclude specific databases from the backup, so that the configuration will only be applied to the databases you want to back up.

Each derived database task is a persistent scheduled entity that runs backup operations on the schedule defined by the parent server-wide task.

  • You can access each derived task to check its latest and next scheduled backups, or to trigger an immediate database backup.
  • The derived tasks continue to share the configuration defined by the server-wide template.
    • Modifying the configuration or excluding databases from the backup can only be done through the parent server-wide task.
    • Deleting the server-wide task will remove all derived tasks.

A backup operation is the actual execution of a backup.
It starts, runs, and completes (or fails).
Once a backup operation is running, you can delay or abort it, e.g., to free up system resources.

For example:

  • You create a server-wide backup task named NightlyBackup that defines a full backup each night at midnight.
  • The server automatically applies your configuration as per-database backup tasks, naming each derived task Server Wide Backup, NightlyBackup.
  • Each derived database task executes a backup operation every midnight.

Creating and managing server-wide backup tasks using the client API​

Creating a server-wide backup task​

To create a server-wide backup task:

  • Define a backup configuration using a ServerWideBackupConfiguration instance.

    • ServerWideBackupConfiguration inherits from PeriodicBackupConfiguration, which defines all configuration options used by both server-wide and regular database backup tasks.
      See the periodic database backup task article for guidance about these options.
    • ServerWideBackupConfiguration adds the following server-wide-specific property:
      • ExcludedDatabases - A list of databases to exclude from the server-wide backup.

  • Pass your populated instance to PutServerWideBackupConfigurationOperation to register the server-wide task, create the derived database tasks, and schedule the backup routine for each database.

  • Example:

    var serverWideBackupConfiguration = new ServerWideBackupConfiguration
    {
        // Task is enabled
        Disabled = false,

        // Task name 
        Name = "FullAndIncrementalBackup",

        // Create a logical backup
        BackupType = BackupType.Backup,

        // Run a full backup every 6 hours
        FullBackupFrequency = "0 */6 * * *",

        // Run an incremental backup every 20 minutes
        IncrementalBackupFrequency = "*/20 * * * *",

        // Keep backups locally
        LocalSettings = new LocalSettings
        {
            FolderPath = backupPath
        },

        // Also upload backups to Azure
        AzureSettings = new AzureSettings
        {
            // Use your Azure credentials here
        },

        // Keep backups for 7 days
        RetentionPolicy = new RetentionPolicy
        {
            Disabled = false,
            MinimumBackupAgeToKeep = TimeSpan.FromDays(7)
        },

        // Encrypt backups using a user-provided Base64 key
        BackupEncryptionSettings = new BackupEncryptionSettings
        {
            EncryptionMode = EncryptionMode.UseProvidedKey,
            Key = "OI7Vll7DroXdUORtc6Uo64wdAk1W0Db9ExXXgcg5IUs="
        },

        // Exclude the Customers database from the server-wide backup
        ExcludedDatabases = new[] 
        { 
            "Customers"
        }
    };

    // Create the server-wide task
    var result = await store.Maintenance.Server.SendAsync(
        new PutServerWideBackupConfigurationOperation(
            serverWideBackupConfiguration));

Getting a derived backup task status​

To retrieve the status of a derived database task after its last run, use GetPeriodicBackupStatusOperation with the task ID.

  • If you don't have the task ID, you can get it using GetOngoingTaskInfoOperation with the names of the task and its database.
  • The retrieved status reflects the most recent completed backup run, whether it was scheduled or triggered manually.
  • The status includes the number of backups performed by the task, and details about the last backup such as the backup timestamp, duration, destination path, and error information (if any).

See GetPeriodicBackupStatusOperation syntax

Example:​

// Database name 
var databaseName = "Products";

// Server-wide task name 
var serverWideTaskName = "FullAndIncrementalBackup";

// Pass the server-wide task name to get the derived task name 
var derivedTaskName = 
    PutServerWideBackupConfigurationCommand.GetTaskName(serverWideTaskName);

// Pass the derived task name to get the derived task info 
var derivedTask = await store.Maintenance.ForDatabase(databaseName).SendAsync( 
    new GetOngoingTaskInfoOperation(derivedTaskName, OngoingTaskType.Backup)) 
    as OngoingTaskBackup;

// Ensure the derived task exists for the chosen database 
if (derivedTask == null) 
{ 
    throw new InvalidOperationException(
        $"The server-wide periodic backup task '{derivedTaskName}' " + 
        $"is not found in database '{databaseName}'."); 
}

// Get the backup status for this database's derived task 
var statusResult = await store.Maintenance.ForDatabase(databaseName).SendAsync( 
    new GetPeriodicBackupStatusOperation(derivedTask.TaskId));

var status = statusResult.Status;

// Status is null if no backup has run yet 
if (status == null) 
{ 
    // No backup has been executed yet for this task 
    return; 
}

// Check for errors in the last backup run 
if (status.Error != null) 
{ 
    string errorMessage = status.Error.Exception; 
    DateTime errorTime = status.Error.At; 
}

// Access last backup details 
bool wasFull = status.IsFull; 
long? lastEtag = status.LastEtag; 
long? durationMs = status.DurationInMs; 
DateTime? lastFullBackup = status.LastFullBackup; 
DateTime? lastIncrementalBackup = status.LastIncrementalBackup;

// Access backup destination details
 string? localBackupDir = status.LocalBackup?.BackupDirectory;

Updating a server-wide backup task​

To update an existing backup task:

  • Retrieve the server-wide task configuration that you want to update.
    • Use GetServerWideBackupConfigurationOperation to retrieve a single configuration by name,
    • Or use GetServerWideBackupConfigurationsOperation to retrieve all existing configurations and select the one you want by a property of your choice.
  • Modify the configuration without changing the existing TaskId.
  • Use PutServerWideBackupConfigurationOperation to apply the modified configuration.

Example:​

// Retrieve existing configuration by name
var existing = await store.Maintenance.Server.SendAsync(
    new GetServerWideBackupConfigurationOperation("FullAndIncrementalBackup"));

// Ensure the task exists
Assert.NotNull(existing);

// Update by modifying the retrieved instance
existing.FullBackupFrequency = "0 */7 * * *";
existing.IncrementalBackupFrequency = "*/20 * * * *";

// Send update
await store.Maintenance.Server.SendAsync(
    new PutServerWideBackupConfigurationOperation(existing));

Deleting a server-wide backup task​

To delete a server-wide backup task and remove all its derived database tasks:

  • Use DeleteServerWideTaskOperation and pass the name of the server-wide backup task you want to delete.

Example:​

// Delete a server-wide backup task by name
await store.Maintenance.Server.SendAsync(
    new DeleteServerWideTaskOperation("FullAndIncrementalBackup", OngoingTaskType.Backup));

Managing backup operations​

After defining a server-wide task, its derived database tasks start executing backup operations as scheduled.
For any derived database task, you can:

  • Trigger the immediate execution of a backup operation, outside of its task schedule.
  • Delay a backup operation that the task has already started.
  • Abort a backup operation that the task has already started.

Triggering an immediate backup operation​

To back up a database immediately using a derived database task:

  • Pass PutServerWideBackupConfigurationCommand.GetTaskName the server-wide task name,
    to get the derived task name.
  • Pass GetOngoingTaskInfoOperation the derived task name,
    to get the derived task info.
  • Pass StartBackupOperation the derived task ID,
    to trigger an immediate backup.

Example:​

// Database name
var databaseName = "Products";

// Server-wide task name
var serverWideTaskName = "DailyBackup";

// Pass the server-wide task name to get the derived task name
var derivedTaskName = PutServerWideBackupConfigurationCommand.GetTaskName(serverWideTaskName);

// Pass the derived task name to get the derived task info
var derivedDatabaseTask = await store.Maintenance.ForDatabase(databaseName).SendAsync(
    new GetOngoingTaskInfoOperation(derivedTaskName, OngoingTaskType.Backup)) as OngoingTaskBackup;

// Ensure the derived task exists for the chosen database
if (derivedDatabaseTask == null)
{
    throw new InvalidOperationException($"The server-wide periodic backup task '{derivedTaskName}' " +
        $"is not found in database '{databaseName}'.");
}

// Get the TaskId of the derived task
long derivedDatabaseTaskId = derivedDatabaseTask.TaskId;

// Decide whether to run full or incremental backup
bool isFullBackup = true;

// Create backup immediately for the chosen database
Operation<StartBackupOperationResult> backupOperation = await store.Maintenance.ForDatabase(databaseName).SendAsync(
    new StartBackupOperation(isFullBackup, derivedDatabaseTaskId));

StartBackupOperation:​

public StartBackupOperation(bool isFullBackup, long taskId)

ParameterTypeDescription
isFullBackupbooltrue - create a full backup
false - create an incremental backup
taskIdlongThe ID of the periodic backup task to use when creating the backup.

Delaying a running backup operation​

To delay the execution of a currently running backup operation:

  • Pass PutServerWideBackupConfigurationCommand.GetTaskName the server-wide task name,
    to get the derived task name.
  • Pass GetOngoingTaskInfoOperation the derived task name,
    to get the derived task info.
  • Ensure that the derived task exists on the chosen database (not null),
    and there is a running backup operation (OnGoingBackup is not null).
  • Pass DelayBackupOperation the operation ID and the delay duration to delay the backup operation.

Example:​

// The database name
var databaseName = "Products";

// Pass the server-wide task name to get the derived task name 
var derivedTaskName = PutServerWideBackupConfigurationCommand.GetTaskName(serverWideTaskName);

// Pass the derived task name to get the derived task info
var derivedTask = await store.Maintenance.ForDatabase(databaseName).SendAsync(
    new GetOngoingTaskInfoOperation(derivedTaskName, OngoingTaskType.Backup)) as OngoingTaskBackup;

// Ensure the derived task exists
if (derivedTask == null)
{
    throw new InvalidOperationException($"The server-wide periodic backup task '{derivedTaskName}' " +
        $"is not found in database '{databaseName}'.");
}

// Ensure there is a running backup operation
if (derivedTask.OnGoingBackup == null)
{
    throw new InvalidOperationException("No running backup operation to delay.");
}

// Delay duration
var delayDuration = TimeSpan.FromHours(1);

// Delay the running backup operation
await store.Maintenance.ForDatabase(databaseName).SendAsync(new DelayBackupOperation(
    derivedTask.OnGoingBackup.RunningBackupTaskId,
    delayDuration));

Aborting a running backup operation​

  • To abort a periodic backup that was started by its derived task as scheduled:

    • Pass PutServerWideBackupConfigurationCommand.GetTaskName the server-wide task name,
      to get the derived task name.
    • Pass GetOngoingTaskInfoOperation the derived task name,
      to get the derived task info.
    • Ensure that the derived task exists on the chosen database (not null),
      and there is a running backup operation (OnGoingBackup is not null).
    • Pass KillOperationCommand the operation ID to abort the backup operation.

    Example:

    var databaseName = "Products";

    // Pass the server-wide task name to get the derived task name
    var derivedTaskName = PutServerWideBackupConfigurationCommand.GetTaskName(serverWideTaskName);

    // Pass the derived task name to get the derived task info
    var derivedTask = await store.Maintenance.ForDatabase(databaseName).SendAsync(
        new GetOngoingTaskInfoOperation(derivedTaskName, OngoingTaskType.Backup)) as OngoingTaskBackup;

    // Ensure the derived task exists
    if (derivedTask == null)
    {
        throw new InvalidOperationException($"The server-wide periodic backup task '{derivedTaskName}' " +
            $"is not found in database '{databaseName}'.");
    }

    // Ensure there is a running backup operation
    if (derivedTask.OnGoingBackup == null)
    {
        throw new InvalidOperationException("No running backup operation to abort.");
    }

    // Abort the backup by killing the running operation 
    await store.Commands(databaseName).ExecuteAsync(
    new KillOperationCommand(derivedTask.OnGoingBackup.RunningBackupTaskId));

  • To abort a backup that was triggered manually using StartBackupOperation:

    • Extract the backup operation ID from the result returned by StartBackupOperation.
    • Use the backup operation ID to abort the operation.
    • Also extract and use the responsible node tag to ensure that the operation is aborted on the correct cluster node.

    Example:

    // Database name
    var databaseName = "Products";

    // Server-wide task name
    var serverWideTaskName = "DailyBackup";

    // Pass the server-wide task name to get the derived task name
    var derivedTaskName = PutServerWideBackupConfigurationCommand.GetTaskName(serverWideTaskName);

    // Pass the derived task name to get the derived task info
    var derivedDatabaseTask = await store.Maintenance.ForDatabase(databaseName).SendAsync(
        new GetOngoingTaskInfoOperation(derivedTaskName, OngoingTaskType.Backup)) as OngoingTaskBackup;

    // Ensure the derived task exists for the chosen database
    if (derivedDatabaseTask == null)
    {
        throw new InvalidOperationException($"The server-wide periodic backup task '{derivedTaskName}' " +
            $"is not found in database '{databaseName}'.");
    }

    // Get the TaskId of the derived task
    long derivedDatabaseTaskId = derivedDatabaseTask.TaskId;

    // Decide whether to run full or incremental backup
    bool isFullBackup = true;

    // Create backup immediately for the chosen database
    Operation<StartBackupOperationResult> backupOperation = await store.Maintenance.ForDatabase(databaseName).SendAsync(
        new StartBackupOperation(isFullBackup, derivedDatabaseTaskId));

    // Kill the running operation by id, routed to the owning node
    long backupOperationId = backupOperation.Id;
    string nodeTag = backupOperation.NodeTag;

    await store.Commands(databaseName).ExecuteAsync(
        new KillOperationCommand(backupOperationId, nodeTag));

Note that after aborting the backup operation, you may need to manually clean up:

  • Partial local files, left while creating the backup.
  • Partial or temporary remote uploads.

Syntax​

Methods​

Server-wide task management​

Creates or updates a server-wide periodic backup task.

public PutServerWideBackupConfigurationOperation(ServerWideBackupConfiguration configuration)


Usage:

PutServerWideBackupConfigurationResponse result = await store.Maintenance.Server.SendAsync(
    new PutServerWideBackupConfigurationOperation(configuration));


ParameterTypeDescription
configurationServerWideBackupConfigurationThe server-wide backup configuration to create or update.
To update an existing task, retrieve the current configuration first (keeping its TaskId unchanged).
Return value
PutServerWideBackupConfigurationResponseContains Name (string) — the name of the created or updated server-wide task,
and RaftCommandIndex (long).

Retrieves all server-wide backup configurations.

public GetServerWideBackupConfigurationsOperation()


Usage:

ServerWideBackupConfiguration[] configs = await store.Maintenance.Server.SendAsync(
    new GetServerWideBackupConfigurationsOperation());


Return value
ServerWideBackupConfiguration[]An array of all server-wide backup configurations.
null if no server-wide backup tasks exist.

Operations​

For syntax details on the operations used in the examples above to trigger, delay, and abort backup operations (StartBackupOperation, DelayBackupOperation, KillOperationCommand), see the database backup operations syntax.

Classes​

Backup configuration classes​

Server-wide backup configuration

class ServerWideBackupConfiguration : PeriodicBackupConfiguration, IServerWideTask
{
    string[] ExcludedDatabases
}

PropertyTypeDescription
ExcludedDatabasesstring[]The list of databases excluded from the server-wide backup.

For syntax details on all configuration classes, enums, and backup destination settings used in the properties above, see the database backup syntax.

Creating and managing server-wide backup tasks via Studio​

Creating a server-wide backup task​

To create a periodic server-wide backup task:

  • Open: Manage server > Server-wide tasks > Add a server-wide task

    Manage server viewManage server view

  • Pick Server-wide periodic backup to create your task.

    Create server-wide taskCreate server-wide task

  • Define the backup configuration as explained in the periodic database-backup task article
    and exclude any database that you don't want to schedule backups for.

    Task configurationTask configuration

    • Exclude databases

      Exclude databaseExclude database

      By default, the server will create a derived database backup task and schedule a backup routine for all databases on the server.
      To exclude databases from the backup, enable the Exclude databases option and select the databases you want to exclude.

    • Backups storage

      Storage settingsStorage settings

      Define a root storage location for backups created by all derived database tasks.
      Each database task will automatically store its backups in a subfolder named after the database, under the root storage location.

      e.g.,

      • for a local folder, define D:\RavenBackups as the root storage location.
        Backups for a database named Products will be stored in D:\RavenBackups\Products.
      • for an FTP destination, define ftp://myserver.com/backups as the root storage location.
        Backups for a database named Products will be sent to ftp://myserver.com/backups/Products.
      • For an S3 destination, define ravendb/backups as the root storage location.
        Backups for a database named Products will be sent to ravendb/backups/Products.

    • Encryption settings

      • When the database is unencrypted:

        • Snapshots are always unencrypted.
        • Logical backups are handled according to the server-wide task encryption settings:
          • Disable encryption to produce unencrypted backups.
          • Enable encryption and provide an encryption key to encrypt the backups.

      • When the database is encrypted:
        Snapshots and logical backups are both always encrypted using the database key.

        Note that logical backups behave differently in this respect when created by a server-wide task vs a regular database backup task.
        See the server-wide encryption section in the overview for additional details.

  • Save the server-wide task.

    Save or CancelSave or Cancel

    Save to store the task and create the derived database tasks,
    or Cancel to discard the server-wide configuration.

Managing server-wide tasks​

Managing the parent server-wide task​

To manage a saved server-wide task, open the Manage server view and select Server-wide tasks.

Backups view with tasksBackups view with tasks

You can:

  • Edit tasks.
  • Enable or disable tasks and all their derived database tasks.
  • Delete tasks and all their derived database tasks.
  • View task details, including -
    • Whether backups are encrypted.
    • Where backups are stored.
    • The retention period for stored backups.
    • Which databases are excluded from the backup.

Managing derived database tasks​

To manage a database backup task derived from a server-wide task:

  • Select a database from the Databases view.
    Select databaseSelect database

  • Open the Tasks view and select Backups.
    The names of backup tasks derived from a server-wide configuration are automatically given a Server Wide Backup prefix.

    Server-wide derived tasksServer-wide derived tasks

    You can:

    • Enable or disable the database task.
    • Create a backup immediately for this database.
    • View task details, including:
      • The node responsible for the backup task.
      • The node where the task was last executed.
      • Whether backups are encrypted.
      • Where backups are stored.
      • Last and next scheduled backups.
      • The retention period for stored backups.

    Editing and deleting the task are available only from the parent server-wide task.

Running a backup operation immediately​

You can trigger the immediate creation of a backup for the database, without waiting for the next scheduled backup.

  • Expand the task details bar as seen above, and click Backup now.
  • You will be given the option to create a full or an incremental backup immediately, based on the server-wide task configuration. Select scopeSelect scope

Delaying or aborting a running backup operation​

To delay or abort a running backup operation (e.g., when a backup takes longer than expected or you need to free up server resources), open the notifications center and find the notification added for the running backup operation.

  • To abort the operation, click the notification's Abort button.
    Abort backupAbort backup

  • To delay the operation:

    • Click the notification's Details button.
      Backup operation notificationBackup operation notification
    • When the operation details view opens, click the Delay backup button at the bottom and select the delay duration. The backup operation will resume when the set period elapses.
      Delay backupDelay backup

In this article