Checkpoints

ZeroFS supports creating named checkpoints for point-in-time snapshots. Checkpoints capture the database state at a specific moment, enabling you to open historical views of your data.

Overview

Checkpoints are named snapshots of your database state. They're useful for:

Point-in-time recovery: Access data as it was at a specific moment
Consistent backups: Create snapshots before risky operations
Historical analysis: Run read-only queries against past states

Creating Checkpoints

Checkpoints are created via RPC commands while ZeroFS is running. This ensures data consistency by coordinating with the active database.

Each checkpoint has:

Name: A unique identifier you choose
ID: An internal UUID
Timestamp: When the checkpoint was created

Create a Checkpoint

# Create a named checkpoint
zerofs checkpoint create -c zerofs.toml my-snapshot

# Output:
# Checkpoint created successfully!
#   Name: my-snapshot
#   ID: 01234567-89ab-cdef-0123-456789abcdef
#   Created at: 2025-01-15 10:30:00

Managing Checkpoints

List Checkpoints

zerofs checkpoint list -c zerofs.toml

Checkpoint Info & Deletion

# Get details about a specific checkpoint
zerofs checkpoint info -c zerofs.toml my-snapshot

# Delete a checkpoint
zerofs checkpoint delete -c zerofs.toml old-snapshot

Opening from a Checkpoint

You can start ZeroFS in read-only mode from a specific checkpoint. This is useful for:

Inspecting historical data
Running read-only analytics on a consistent snapshot
Verifying data integrity

# Start ZeroFS from a checkpoint (read-only)
zerofs run -c zerofs.toml --checkpoint my-snapshot

# Mount and access historical data
mount -t nfs 127.0.0.1:/ /mnt/snapshot
ls /mnt/snapshot  # See data as it was at checkpoint time

Opening from a checkpoint is always read-only. The checkpoint data is preserved and cannot be modified.

Use Cases

Pre-Migration Snapshots

Create checkpoints before major changes:

# Checkpoint before migration
zerofs checkpoint create -c zerofs.toml pre-migration

# Run migration...

# If something goes wrong, you can inspect the pre-migration state
zerofs run -c zerofs.toml --checkpoint pre-migration

Regular Backups

Maintain periodic checkpoints:

# Create daily checkpoints
zerofs checkpoint create -c zerofs.toml daily-2025-01-15

# List available checkpoints
zerofs checkpoint list -c zerofs.toml

# Clean up old checkpoints
zerofs checkpoint delete -c zerofs.toml daily-2025-01-01

Configuration

Checkpoint commands require the RPC server to be enabled:

zerofs.toml

[servers.rpc]
addresses = ["127.0.0.1:7000"]
unix_socket = "/tmp/zerofs.rpc.sock"

The RPC server must be running (via zerofs run) for checkpoint create, list, delete, and info commands to work.

Learn more about configuration options