Skip to content

Commit 235558d

Browse files
author
Elrond
committed
docs(database): describe the fence prerequisite against current deletion checks
Startup and deletion validation no longer require a fence on any table, and every serving writer already goes through admission. The remaining blocker for a trigger-less tenant table is the desired-state fence loop. Also name the leased-completion admission exception and fix mid-sentence wraps. Signed-off-by: Elrond <28d6302a099e5225b02c4155ac4236e4912603df2ab08dbfc2f4fef08ce598c8@buzz.block.builderlab.xyz>
1 parent 00ab4a4 commit 235558d

3 files changed

Lines changed: 48 additions & 44 deletions

File tree

‎ARCHITECTURE.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -526,10 +526,9 @@ shape is an explicit transition, not a flag day:
526526
the operational evidence path for rollout safety.
527527

528528
The database end state (a declarative schema source, applied out of band at
529-
scale; no triggers, functions, or foreign keys;
530-
backfills outside migrations) and the
531-
expand → deploy → backfill → contract rules every schema change follows are in
532-
[docs/database.md](docs/database.md).
529+
scale; no triggers, functions, or foreign keys; backfills outside migrations)
530+
and the expand → deploy → backfill → contract rules every schema change follows
531+
are in [docs/database.md](docs/database.md).
533532

534533
**Does NOT:** cache queries, implement connection pooling logic (delegated to sqlx), or make network calls outside Postgres.
535534

‎docs/database.md‎

Lines changed: 41 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -79,53 +79,59 @@ retirement sequence below.
7979
**No exception for the community write fence.** A new table MUST NOT get a
8080
fence trigger, including by calling the existing helper
8181
`attach_community_write_fence`. Writers of a new tenant-owned table MUST be
82-
fenced in the application instead, by community admission. Serving writers,
83-
including fleet sweeps (one community at a time), are admitted by
82+
fenced in the application instead, by community admission. New serving work,
83+
including fleet sweeps (one community at a time), is admitted by
8484
`DeletionStore::guard_transaction`, which takes the shared community deletion
85-
lock and refuses a community that is not `active`. Most open their transaction
86-
with `begin_community_write_transaction` or one of its variants
85+
lock and refuses a community that is not `active`. Most writers open their
86+
transaction with `begin_community_write_transaction` or one of its variants
8787
(`crates/buzz-db/src/runtime/mod.rs`), which returns an `AdmittedTx`
88-
(`crates/buzz-db/src/runtime/admitted_tx.rs`). Helpers that take
89-
`&mut AdmittedTx` reject a raw transaction at compile time, but crate code can
90-
still bypass the type, so the fence triggers remain the authoritative backstop
91-
(ARCHITECTURE.md § *Supported Writer Contract*). A table without a trigger has
92-
no database backstop. The remaining fence-retirement work makes every writer of
93-
every fenced table go through admission, then drops the fence triggers and
94-
functions. That work MUST also update ARCHITECTURE.md § *Dual enforcement*.
95-
96-
**Today this blocks new tenant-owned tables.** Community deletion's catalog
97-
checks still assume that every tenant-scoped table carries a trigger fence:
98-
99-
- An unlisted `community_id` table, fenced or not, fails the exact-set check
100-
against `EXPECTED_SCOPED_TABLES`
101-
(`community deletion catalog drift (missing=…, unknown=…)`). Listing it
102-
without a trigger fails the write-fence drift check. Either way, deletion
103-
fails closed for every community, not only the new table's.
104-
- Relay startup refuses a binary that lists the table in
105-
`EXPECTED_SCOPED_TABLES` when the database has no live fence on it
106-
(`community serving write fences missing`).
88+
(`crates/buzz-db/src/runtime/admitted_tx.rs`). One exception is deliberate:
89+
a write that finishes under an already-admitted serving lease
90+
(`insert_event_with_serving_write_guard`, through
91+
`AdmittedTx::admit_with_serving_lease`) is checked by
92+
`guard_transaction_with_serving_lease`, which lets that exact unexpired lease
93+
complete while the community is `quiescing`. Keep it.
94+
95+
Helpers that take `&mut AdmittedTx` reject a raw transaction at compile time,
96+
but crate code can still bypass the type, so the fence triggers remain the
97+
database backstop until they are dropped (ARCHITECTURE.md § *Supported Writer
98+
Contract*). A table without a trigger has no database backstop. Every serving
99+
writer of a fenced table already goes through admission. The remaining
100+
fence-retirement work drops the fence triggers and functions, and MUST also
101+
update ARCHITECTURE.md § *Dual enforcement*.
102+
103+
**Today this blocks new tenant-owned tables.** Startup and deletion validation
104+
no longer require a fence on any table; they pass with every universal fence
105+
object dropped (`migration_schema_fence_objects_are_optional_for_serving_and_deletion`
106+
in `crates/buzz-db/src/store/deletion.rs`). Two things still matter:
107+
108+
- Deletion's catalog check is an exact set. A `community_id` table missing from
109+
`EXPECTED_SCOPED_TABLES`, fenced or not, fails it
110+
(`community deletion catalog drift (missing=…, unknown=…)`), and deletion
111+
fails closed for every community, not only the new table's. Listing the
112+
table is enough to pass.
107113
- Desired-state bootstraps run `schema/community_write_fence.sql`, which
108-
attaches a fence trigger to every `community_id` table automatically.
114+
attaches a fence trigger to every `community_id` table not excluded by
115+
`community_write_fence_excluded_table`. A fresh desired-state database would
116+
put a trigger on the new table and a migrated one would not, so the two
117+
schema paths would diverge.
109118

110-
So before a feature can add a tenant-owned `community_id` table, these checks
111-
must recognise application-fenced tables, and the desired-state loop must stop
112-
attaching triggers to them. That change belongs to the fence-retirement work.
113-
Land it before the feature, or as the feature's first PR. Do not work around
114-
it with a trigger, or with an entry in `community_write_fence_excluded_table`
115-
for a table the community owns.
119+
So before a feature can add a tenant-owned `community_id` table, the
120+
desired-state bootstrap must stop attaching fence triggers. That change belongs
121+
to the fence-retirement work. Land it before the feature, or as the feature's
122+
first PR. Do not work around it with a trigger, or with an entry in
123+
`community_write_fence_excluded_table` for a table the community owns.
116124

117125
#### Checklist: adding a tenant-owned `community_id` table
118126

119-
After the catalog change above has landed, all in the same PR:
127+
After the desired-state change above has landed, all in the same PR:
120128

121129
- [ ] Every writer of the table goes through community admission
122130
(`begin_community_write_transaction` or another constructor that returns
123131
`AdmittedTx`). Nothing writes the table outside it.
124132
- [ ] No fence trigger: no `attach_community_write_fence` call in the
125133
migration and no `schema/triggers/` file.
126-
- [ ] The table in `EXPECTED_SCOPED_TABLES` (`crates/buzz-db/src/store/deletion.rs`),
127-
plus any registration the catalog change introduces for
128-
application-fenced tables.
134+
- [ ] The table in `EXPECTED_SCOPED_TABLES` (`crates/buzz-db/src/store/deletion.rs`).
129135
- [ ] The table in `PURGE_SCOPED_TABLES` in the same file, ordered child
130136
before parent. A table missing here keeps its rows after the purge, and
131137
deletion verification fails closed.
@@ -358,7 +364,7 @@ before the contract have already committed, so an old pod that restarts hits
358364
| Add `CHECK`, `UNIQUE`, or a narrower index | Old writes violate it, or an old `ON CONFLICT` target no longer matches an index | Deploy writers that satisfy it, backfill, then add it. Add a `CHECK` as `NOT VALID`, then `VALIDATE CONSTRAINT` in a later step. Keep every index an old `ON CONFLICT` names until no deployed code uses it |
359365
| Add an enum value that new code writes | Old code fails to decode the unknown variant | Deploy readers that accept the value, then deploy writers that produce it |
360366
| Drop a column, table, index, trigger, function, or FK | Old code reads it or relies on its side effect | Contract step only, after the release that stops relying on it is fully deployed |
361-
| Add a table with a `community_id` column | The old relay's exact-set deletion catalog check (`EXPECTED_SCOPED_TABLES`) sees an unknown table, so community deletion fails closed until the new release deploys. Serving is unaffected, apart from the auto-migration restart case in Rule 5 | Allowed, after Rule 1's catalog change for a tenant-owned table. Keep the gap between expand and deploy short, and do not run community deletion during it |
367+
| Add a table with a `community_id` column | The old relay's exact-set deletion catalog check (`EXPECTED_SCOPED_TABLES`) sees an unknown table, so community deletion fails closed until the new release deploys. Serving is unaffected, apart from the auto-migration restart case in Rule 5 | Allowed. For a tenant-owned table, only after the desired-state change in Rule 1. Keep the gap between expand and deploy short, and do not run community deletion during it |
362368
| `SELECT *` or `RETURNING *` decoded by position | Column order differs between desired-state and migrated databases and changes when columns are added | Select named columns |
363369

364370
#### Adding `NOT NULL` to a populated table

‎migrations/AGENTS.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,10 @@ Before changing anything in this directory, read
1616
Do not add new gateway tables here.
1717
- Never edit a merged migration. Fix forward.
1818
- Adding a `community_id` table has its own checklist in that document. A
19-
tenant-owned one is blocked until deletion's catalog checks accept
20-
application-fenced tables.
19+
tenant-owned one is blocked until desired-state bootstraps stop attaching
20+
fence triggers to every `community_id` table.
2121
- Keep every migration safe for the relay that is currently deployed, whether
22-
migrations run at startup or out of band. Ship in
23-
this order: new schema, then new code, then backfill, then constraints and
24-
cleanup. A contract migration fails closed if its backfill has not run, and
22+
migrations run at startup or out of band. Ship in this order: new schema,
23+
then new code, then backfill, then constraints and cleanup. A contract migration fails closed if its backfill has not run, and
2524
its release notes name the writer release that upgrades must not skip.
2625
- Bound every lock (`SET LOCAL lock_timeout`).

0 commit comments

Comments
 (0)