Checkpoints give SlateDB a cheap way to hold onto one stable view of the database while the live database keeps moving. They are useful for long-running reads, read-only clients that need a fixed view, clones, and administrative workflows that must keep old SSTs and manifests alive while compaction and garbage collection continue in the background.

A checkpoint is a durable reference to one manifest version. SlateDB stores checkpoints in the latest manifest. Each checkpoint records an ID, the pinned manifest_id, its creation time, an optional expiration time, and an optional name.

Creating a checkpoint does not copy WAL or SST files. It only adds metadata to the manifest, so it is cheap. The pinned manifest still matters, though, because it defines the L0 SSTs, sorted runs, and other database state that readers see.

What It Protects#

The garbage collector keeps any manifest and SST file that is still reachable from an active checkpoint. That is how SlateDB holds a stable read view open while compaction and garbage collection continue in the background.

When a checkpoint expires or is deleted, SlateDB removes that checkpoint entry from the manifest. After that, GC may reclaim manifests and SSTs that are no longer referenced by the latest database state or by any other checkpoint. Garbage Collection covers the cleanup flow.

A new checkpoint can also be created from an existing checkpoint through CheckpointOptions::source. In that case, the new checkpoint reuses the source checkpoint's manifest_id. This is useful when you want a different lifetime or name without pinning newer database state.

How SlateDB Creates Checkpoints#

Db::create_checkpoint creates a checkpoint from an open writer handle. CheckpointScope::All flushes WAL data and memtables first, so the checkpoint includes writes issued before the call. CheckpointScope::Durable skips that extra flushing work and only includes data that was already durable.

Admin::create_detached_checkpoint edits the manifest directly. It does not flush a writer's in-memory state first, so recent unflushed writes are not included.

CheckpointOptions lets you set a lifetime, a source checkpoint, and an optional name. Names are labels for listing checkpoints. They are not unique.

Readers and Background Tasks#

DbReader uses checkpoints to separate reader lifetime from writer lifetime. You choose how the reader tracks database state by passing a DbReaderMode:

• ManagedCheckpoint (default): The reader creates and maintains checkpoints while following the latest database state.
• Checkpoint(id): The reader remains pinned to the database state referenced by the supplied checkpoint. It does not follow newer manifests or newer WAL data.
• FollowLatest: The reader follows the latest manifest without creating a checkpoint. This mode performs no object-store writes and provides no protection from garbage collection. Reads may fail if referenced objects are deleted. This mode is useful for read-only access to databases not being actively written to, for mirrored databases where manifest changes might not be allowed, or for readers willing to handle missing objects gracefully.

DbReaderOptions::checkpoint_lifetime controls how long a ManagedCheckpoint reader's checkpoint lives before it must be refreshed.

SlateDB also uses short-lived internal checkpoints during some background transitions. For example, the compactor writes a temporary checkpoint before publishing a manifest that drops obsolete SST references. That keeps recently replaced SSTs readable until GC can safely remove them.

Clones#

Clones build on the same mechanism. A clone starts from a checkpoint in the source database, then writes new data into its own path while continuing to reference source SSTs. RFC 0004 describes the full checkpoint and clone design.