WAL & Checkpoints

What you'll learn

What the Write-Ahead Log is, when to checkpoint, and how to trigger a manual flush.

What the WAL is

Every write goes to the WAL (Write-Ahead Log) first — a plaintext append-only file. This guarantees crash recovery: if the process dies mid-write, the WAL replays on next boot and no data is lost.

The WAL is separate from the encrypted strand segments. On boot: 1. WAL replays into memory 2. Segment files are loaded 3. New writes go to WAL first, then to segment on checkpoint

Checkpoint (flush WAL to segments)

curl -s -X POST http://localhost:7475/v1/control/checkpoint \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  | python3 -m json.tool

This forces an fsync of all pending WAL data to encrypted segment files. WAL is then truncated.

When to checkpoint manually: - Before taking a snapshot (ensures snapshot captures all recent writes) - Before switching to maintenance mode - Before shutting down for a planned restart

Health and WAL status

curl -s http://localhost:7475/v1/control/status \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  | python3 -m json.tool

Response includes wal_pending_records — how many writes are in the WAL but not yet in a segment.

Challenge

Write 10 records, check wal_pending_records, run checkpoint, check again — it should be 0.

---