Module 11 · Chapter III — The engines
Postgres WAL on the floor.
The engines chapter built one durable floor — Champ accepts, CubDB/Fjall holds, Graft commits one LSN to Tigris behind the fence. But that floor carries the available-first tier: the cache and the stream log. The money lives elsewhere — in Postgres, the consistency-first ledger — and its write-ahead log never reaches the floor. This module is the PROPOSED design for bringing the ledger's WAL LSN onto the same Tigris floor and the same one cursor.
graft.pg-wal-archive.design.md, the fork ruled A→B); this page teaches the proposal, not as-built code.Why the ledger isn't on the floor — yet
graft.pg-wal-archive.design.mdThe platform segments its CAP trade per surface, and durability follows the split. The available-first tier — the near-cache and the EchoMQ stream log — rides the floor this chapter built: its pages and its trimmed stream slices become Graft commits replicated to Tigris, and the commit LSN binds replica, consumer, and store on one cursor (Module 13). The consistency-first ledger is a different surface: balances and an append-only transaction ledger in Postgres, mutated all-or-nothing, where a committed payout must never be lost. Its durable record is its own write-ahead log, with its own LSN — a different log over different bytes. Graft replicating its commit LSN to Tigris does not archive Postgres's WAL; the two are disjoint, and the money's off-site recovery is, today, unsolved on the floor.
That is the gap this module closes in design. Postgres point-in-time recovery and a streaming replica are the ledger's launch prerequisites (codemojex.postgres.md, “the work before real money”), and the question is whether to answer them with a parallel, off-platform backup tool or to bring the WAL onto the engine, the fence, the bucket, and the cursor the rest of the floor already shares. The design surfaces that as a four-arm fork and rules it; the dives walk the idea, the mechanism, and the decision.
The three dives
module 11Two LSN worlds
The Graft commit LSN and the Postgres WAL LSN — why they are disjoint logs over disjoint data, and what the ledger's durability gap actually is.
Dive 11.2The archive_command is the fence
Postgres requires archive_command to be idempotent and never to clobber a same-named segment — exactly the create-if-not-exists the engine commits with (Module 9). One fence, reused; the WAL-archive manifest as the authoritative frontier.
A then B, forward-tense
The surfaced fork — four arms from off-the-shelf WAL-G to a Graft pageserver — the ruling A→B, and why borrowed restore correctness comes before engine elegance for money.
Status & check
The fork is recorded and ruled in graft.pg-wal-archive.design.md: Arm A (WAL-G/pgBackRest → Tigris) then Arm B (a read-only Graft WAL-frontier lane on the change-feed); Arm C (a Graft-native WAL-archive Volume) is deferred, Arm D (a Graft pageserver under a replica) is declined at present scale. No arm is built.
Without code: why doesn't the Graft+Tigris floor already cover Postgres PITR, and what single object-store primitive lets the WAL ride the same fence as a Graft commit? “Two disjoint logs; create-if-not-exists” means you have the module.
References & sources
- Echo records
- graft.pg-wal-archive.design.mdthe surfaced fork (four arms), ruled A→B
- bus-and-persistencethe commit LSN as the one cursor the WAL LSN would join
- the create-if-not-exists fencethe fence reused for archive_command
- codemojex.postgres.mdthe ledger's PITR prerequisite, the archive_mode hazard
- External
- PostgreSQL · Continuous Archiving & PITRarchive_command, recovery_target_lsn, timelines
- WAL-GWAL archiving + base backups to S3-compatible storage
- pgBackRestbackup & restore with validation