Skip to main content

CDC Sink: Backup/Restore Task

Back up CDC Sink task​

CDC Sink tasks are backed up automatically as part of the database record.
No CDC Sink-specific backup setting is required; the task configuration is included in both logical and snapshot backups.

This applies whether you use a per-database backup task or a server-wide backup task,
which applies the backup configuration to each included database.

Backup via Client API​

Use UpdatePeriodicBackupOperation to create or update a periodic backup task.
Learn more in Creating and managing periodic backups using the client API.

var backupConfig = new PeriodicBackupConfiguration
{
    Name = "DailyBackup",
    BackupType = BackupType.Backup,   // or BackupType.Snapshot
    FullBackupFrequency = "0 2 * * *", // every day at 02:00
    LocalSettings = new LocalSettings { FolderPath = @"/backups/db" }
};

await store.Maintenance.SendAsync(new UpdatePeriodicBackupOperation(backupConfig));

Backup via Studio​

Restore CDC Sink task​

Restoring the database recreates the CDC Sink task from the database record in the backup.
The restored task keeps the enabled/disabled state it had in the backup.

Set DisableOngoingTasks = true if you do not want the CDC Sink task (or any other ongoing task)
to start after the database is restored.

Restore via Client API​

Restore the database with RestoreBackupOperation.
Learn more in Restoring from backup using the client API:

var restoreConfig = new RestoreBackupConfiguration
{
    DatabaseName = "RestoredDb",
    BackupLocation = @"/backups/db/2026-07-07-02-00",

    // Recommended when restoring to a new environment so ongoing tasks
    // stay disabled until you've reviewed their settings:
    DisableOngoingTasks = true
};

var restoreOp = await store.Maintenance.Server.SendAsync(
    new RestoreBackupOperation(restoreConfig));
await restoreOp.WaitForCompletionAsync();

Restore via Studio​

  • From Databases → New database → from Backup, choose the backup location.
    Learn more in Restoring from backup using Studio.

  • Enable Disable ongoing tasks after restore if you do not want the CDC Sink task to begin consuming changes until you are ready.

Restore considerations​

Restored enabled tasks can start immediately​

  • If DisableOngoingTasks is left as false, a CDC Sink task that was enabled when the backup was created becomes active immediately and can connect to the source database.

  • When restoring to a new environment, verify the connection string and source availability first.
    For PostgreSQL, also confirm that the referenced publication exists and that the replication slot can be consumed, or configure dedicated names before enabling the restored task.

  • The task's saved CDC progress is restored from the @cdc-states/<task name> document as it existed in the backup. If no matching state document exists, the task starts fresh and performs an initial load unless SkipInitialLoad is set.

PostgreSQL: shared replication slot​

  • Restore copies the task's SlotName and PublicationName unchanged.

  • A PostgreSQL replication slot can be consumed by only one connection at a time.
    If the origin database's task is still enabled, the restored task cannot attach to the same slot and enters fallback mode, reporting an error such as Process is in error recovery (fallback mode)....
    Learn more in One Active Consumer per Slot.

  • Disable the task on one of the two databases (or restore with DisableOngoingTasks = true),
    or give the restored task its own slot and publication before enabling it.

PostgreSQL: saved LSN no longer retained by the slot​

  • The restored task uses the LastLsn saved in its @cdc-states/<task name> document.
    This works only if the PostgreSQL replication slot can still serve WAL from that position.

  • If the slot was dropped and recreated after the backup, or if PostgreSQL no longer retains the WAL needed for the saved LastLsn, the slot's restart_lsn can be ahead of the restored LastLsn.
    Changes in that gap cannot be recovered from the slot.

  • When this happens, CDC Sink raises a warning notification stating that the slot's restart LSN is ahead of the saved position. To start over from the current source data, remove the saved CDC Sink state (@cdc-states/<task name>) or create the task with a new name, then let the initial load run again.
    If the gap might include deletes, verify or rebuild the affected target documents as needed.

  • To avoid this gap, restore the source database and the RavenDB database to consistent points in time,
    and do not drop the slot while a backup that references it may still be restored.

Behavior summary​

AspectBackup / Restore behavior
Task configurationIncluded in the backup; recreated on restore
Enabled/disabled statePreserved from the backup, unless DisableOngoingTasks = true
Saved CDC progress
(@cdc-states/<task name>)		Restored as it existed in the backup; if no matching state document exists,
the task starts fresh unless SkipInitialLoad is set
PostgreSQL slot / publicationNot backed up; the restored task references the same names,
so the publication must exist and the slot must be consumable

In this article