Backup and restore

Backup and restore #

Pizza does not have a first-class backup/restore HTTP API yet — this page describes what exists today and the supported manual procedure.

What exists today #

• Raft metadata snapshots. The catalog’s Raft log is periodically snapshotted (node.snapshot_per_events), so cluster metadata (namespaces, collections, schemas, shard routing) has its own durability story independent of the data plane.
• The trash. Deleting a namespace or a collection (or replacing shards) only touches metadata: the data directories are moved into <data_path>/trash/ and physically deleted by a background sweeper only after trash.retention_secs (default 1 day) elapses. A deleted namespace is captured as ONE item with a restore snapshot per collection, so the whole namespace — all collections, original shard placements included — can be brought back via the Trash APIs. Every restore is preceded by a read-only shard-completeness verification, and a restore whose data is provably incomplete is refused rather than silently coming back empty. This gives a grace window against accidental deletes, not a backup.

Manual backup #

A shard’s durable state is its built FIRE segments plus its WAL tail — both live under the node’s data directory. To take a consistent copy of a single-node deployment:

Restore a trash item

Restore a trash item #

Restore a trashed collection — or a whole deleted namespace — back into the cluster, cluster-coordinated: every holder node moves its copy of the data back, the metadata is re-registered through Raft with the ORIGINAL collection/rolling/shard UUIDs, and the recorded shard placements are replayed so every engine re-opens its original working directory with all documents.

Examples #

Restore a deleted namespace under a new name (every collection comes back inside it):

Cluster-wide recycle bin

Cluster-wide recycle bin #

Accidental deletes used to be a race against the sweeper: deleting a namespace only dropped metadata, and the data directories drifted into the trash WITHOUT a recovery snapshot — permanently unrestorable. The recycle bin is now a first-class, cluster-wide surface with a namespace-centric view, a pre-restore integrity check, and one-request restore:

# One cluster-wide list — every node's trash merged by item, grouped by
# namespace, with the delete-time snapshot summary of each item.
GET /_cluster/trash

Deleting a namespace captures a restore snapshot for every collection it contains, so the WHOLE namespace comes back as a unit — original schemas, shard UUIDs, partition routing and placements included:

Trash APIs

Trash APIs #

The trash (recycle bin) is node-local filesystem state — deleted namespaces and collections are moved into <data_path>/trash/ and physically deleted only after trash.retention_secs elapses. These cluster-level APIs aggregate every node’s trash on the server side and give you one namespace-centric view, a read-only shard-completeness verification, and cluster-wide restore/purge:

• List the cluster trash
• Verify a trash item
• Restore a trash item
• Delete a trash item everywhere
• Empty the trash everywhere

Deleting a namespace (DELETE /_namespace/<name>) now moves the whole namespace — every collection, with a restore snapshot per collection — into the trash as a single item; restoring it brings back all collections with their original schemas, shard UUIDs and placements. Deleting a collection keeps the per-collection behavior it always had.