Checkpoints

A checkpoint is a fast, consistent snapshot of an entire RocksDB database on disk. RocksDB creates the checkpoint by hard-linking SST files and copying anything that can change (the manifest, the current WAL). The result is a directory you can tar, rsync, or open with RocksDb.OpenReadOnly.

Compared to a logical snapshot, a checkpoint is on disk — perfect for backups, point-in-time forks, or seeding a follower.

Upstream reference: Checkpoints wiki.

Creating a checkpoint

using (var cp = db.Checkpoint())
{
    cp.Save("/var/backups/myapp/2026-05-18");
}

The target directory must not exist — RocksDB creates it. Hard-links keep the operation O(number-of-SST-files) regardless of database size, so checkpoints are typically a few milliseconds.

Same filesystem

Hard links only work within a single filesystem. To copy a checkpoint to a different volume, Save first, then copy the resulting directory.

What's in the checkpoint?

Hard links to every live SST file.
A copy of the MANIFEST and CURRENT files.
A copy of the current WAL (so writes since the last flush are included).
Live OPTIONS file.

The checkpoint is a valid, openable RocksDB directory:

using var restored = RocksDb.OpenReadOnly(
    new DbOptions(),
    "/var/backups/myapp/2026-05-18",
    errorIfLogFileExists: false);

string v = restored.Get("k");

Backup patterns

Hot backup

Create a checkpoint, then tar the directory and ship it offsite. The source DB keeps running.

Fork for analysis

Checkpoint, then run heavy analytical scans against the read-only copy without slowing down production.

Seed a follower

Checkpoint, copy the directory to another machine, then attach a secondary instance or replay WAL on top.

A copy-on-demand backup loop

public static void NightlyBackup(RocksDb db, string root)
{
    var stamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH-mm-ssZ");
    var dest  = Path.Combine(root, stamp);

    using var cp = db.Checkpoint();
    cp.Save(dest);

    Console.WriteLine($"Checkpoint at sequence {db.GetLatestSequenceNumber()} -> {dest}");
}

Pair this with the GetLatestSequenceNumber value to record exactly what was captured.

Restoring

There is no special "restore" operation — a checkpoint is a database. To restore:

Stop the writer (or fence it off).
Move the checkpoint directory into place.
Open it with RocksDb.Open.

If you only want a read-only view, just OpenReadOnly the checkpoint directory directly.

Lifecycle

Checkpoint is IDisposable. Wrap the call in using (as in the examples) so the native checkpoint object is released. Disposing the checkpoint does not delete the on-disk backup directory.

using (var cp = db.Checkpoint())
{
    cp.Save("/var/backups/myapp/2026-05-18");
}

Save also accepts a logSizeForFlush argument — if the WAL is smaller than this many bytes, RocksDB flushes the MemTable before snapping, so the checkpoint covers everything written so far. Default is 0 (no automatic flush).