docs(architecture): ADR-009 — pg-lo admitted as the fs tier's second engine on POC #7
- ADR-009 (new): postgres Large Objects ship as the fs tier's second engine (feature pg-lo, default-off), admitted on POC #7's passed gate (contract 10/10, durable put ~= fs at >=1 MiB, lo_get window gets, transactional LO lifecycle = zero crash orphans). Engine shape: companion table (lo_entries) is the contract authority; put = one tx (lo_create + lowrite + row + pin); get = descriptorless lo_get windows (lo_*64 discipline); named operator deltas (catalog space never returned / autovacuum inherited / sweep for the legacy bypass class only) and named performance deltas (cached-get 20-50x behind page-cache fs single-stream, ~700 MB/s aggregate at 16 readers = the fleet serving picture). - Ripple: backends-and-dispatch (pg-lo shipped; fleet locality contract gains the whole-fleet-pg-lo option), overview (layer map, feature table + pg-lo row, OQ -> shipped pointer), requirements (engine def + REQ-2 note updated), README (current-state + ADR table), store-api (invariant 1/6 engine lists), ADR-008 Status amendment (pg-lo posture superseded by ADR-009), open-questions (audit trail completed: decided -> sequenced -> completed). Verification: docs-only; all cross-references resolve (ADR/REQ/POC); register, findings, spec, and both engine-ADR status lines agree.
This commit is contained in:
1 parent
cee97defba
commit
9bbe6f3ad9
8 files changed
+226
-39
No files matched your search
@@ -128,7 +128,7 @@ sweep-outcome CI gate, run against dockerized postgres under
|
||||
near-linearly to ~37k puts/s at 24 conns — the only engine whose
|
||||
throughput *increases* under concurrency.
|
||||
|
||||
### fs backend (feature `fs`, default-on); engines: `local` (default) + `pg-lo` (candidate)
|
||||
### fs backend (feature `fs`, default-on); engines: `local` (default) + `pg-lo` (feature `pg-lo`, default-off)
|
||||
|
||||
Large blobs. Like the kv tier (ADR-007), the fs tier is **one contract,
|
||||
multiple engines** — the medium is a per-node constructor choice
|
||||
@@ -142,24 +142,31 @@ for fleets):
|
||||
rename for the two-pass unknown-length path; pread-based range
|
||||
reads (POC #3 finding A2 — local range serving is sound, e.g. for
|
||||
packfiles).
|
||||
- **`pg-lo` engine** (candidate, *not shipped*; ADR-008): postgres
|
||||
Large Objects as the fs tier's storage — the same engine-behind-
|
||||
one-trait move as ADR-007, one tier over. Admission is gated on
|
||||
POC #7's measured evidence (passed 2026-10-03:
|
||||
`docs/research/poc-pglo-findings.md` — durable put ≈ fs's durable
|
||||
put, `lo_get` window gets, companion-table authority, clean
|
||||
crash-orphan behavior) and its own engine ADR (see
|
||||
`docs/research/poc-pglo-spec.md`).
|
||||
- **Fleet locality contract (ADR-008):** over one shared pool, the fs
|
||||
tier is either shared media (every node's `local` root on the same
|
||||
fleet-shared media — soundness caveats and the required media
|
||||
guarantees in ADR-008) or re-routed (one storage node serves pool
|
||||
large-blob content via the ops surface; client nodes are
|
||||
kv-tier-only over pool content). Mixed per-node-local fs tiers over
|
||||
one pool is the partitioning failure this contract exists to
|
||||
prevent — a documented deployment invariant the constructor cannot
|
||||
fully prove but must be declared against (ADR-008 names the
|
||||
enforceable seam and the detection symptom).
|
||||
- **`pg-lo` engine** (shipped, feature `pg-lo`, default-off; ADR-009):
|
||||
postgres Large Objects as the fs tier's storage — the same
|
||||
engine-behind-one-trait move as ADR-007, one tier over, admitted on
|
||||
POC #7's measured evidence (contract 10/10 exact-count tests;
|
||||
durable put ≈ fs durable put at ≥1 MiB, beats it <1 MiB on the POC
|
||||
disk; gets ride descriptorless `lo_get(oid, off, len)` windows over
|
||||
the companion table as contract authority; LO creation
|
||||
transactional — zero crash orphans). Named deltas: catalog space
|
||||
reused-but-never-returned (monitor rel size; `VACUUM FULL` is the
|
||||
operator's shrink path), autovacuum inherited, cached-get 20–50×
|
||||
behind page-cache fs single-stream (~700 MB/s aggregate at 16
|
||||
readers — the fleet serving picture).
|
||||
- **Fleet locality contract (ADR-008, extended by ADR-009):** over one
|
||||
shared pool, the fs tier is one of: shared media (every node's
|
||||
`local` root on the same fleet-shared media — soundness caveats and
|
||||
the required media guarantees in ADR-008), re-routed (one storage
|
||||
node serves pool large-blob content via the ops surface; client
|
||||
nodes are kv-tier-only over pool content), **or `pg-lo` for the
|
||||
whole fleet** (ADR-009 — one engine, no shared media, no re-routing;
|
||||
pool content lives in the same pg instance the kv tier rides).
|
||||
Mixed per-node-local fs tiers over one pool is the partitioning
|
||||
failure this contract exists to prevent — a documented deployment
|
||||
invariant the constructor cannot fully prove but must be declared
|
||||
against (ADR-008 names the enforceable seam and the detection
|
||||
symptom).
|
||||
|
||||
### mem backend (feature `mem`, default-off)
|
||||
|
||||
|
||||
Reference in new issue
Block a user