Skip to content

Commit a481b5b

Browse files
TheSentinel454Elrondclaude
committed
docs(db): reconcile Rule 3 with inline index builds
Rule 3 forbade any write-blocking scan, contradicting Rule 6's bounded inline CREATE INDEX. Limit it to large tables and allow the budgeted build. State that the prebuild-guard lint matches only its literal wording, and that 0078 refuses populated tables only when applied as SQL. Co-authored-by: Elrond <28d6302a099e5225b02c4155ac4236e4912603df2ab08dbfc2f4fef08ce598c8@buzz.block.builderlab.xyz> Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Luke Tornquist <[email protected]>
1 parent 5ca55f9 commit a481b5b

2 files changed

Lines changed: 9 additions & 6 deletions

File tree

‎docs/artifact-sync-deployment.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,8 @@ CREATE INDEX CONCURRENTLY artifact_revisions_moves
4242
```
4343

4444
Migration `0078` verifies each index definition and its valid, ready, and live
45-
flags. It refuses a populated table whose index is missing. A fresh empty
45+
flags. Applied directly as SQL, it refuses a populated table whose index is
46+
missing. A fresh empty
4647
database can build the indexes under the migration's short budgets.
4748
Migration `0076` also verifies the exact definition and all three flags.
4849
Remove an invalid index with `DROP INDEX CONCURRENTLY` before a new build.

‎docs/database.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -205,9 +205,10 @@ deletes to ship first, then the constraint drop as a separate contract step.
205205
### 3. Backfills are not migrations
206206

207207
A migration MUST contain schema changes only. It MUST NOT `UPDATE`, `INSERT`,
208-
or `DELETE` existing rows, and MUST NOT scan or rewrite a table while holding a
209-
write-blocking lock. Scans that do not block writes, such as
210-
`VALIDATE CONSTRAINT` or a bounded concurrent index build, are allowed (Rule 6).
208+
or `DELETE` existing rows, and MUST NOT scan or rewrite a large table while
209+
holding a write-blocking lock. Scans that do not block writes, such as
210+
`VALIDATE CONSTRAINT` or a concurrent index build, are allowed, as is a plain
211+
`CREATE INDEX` under Rule 6's lock and statement budgets (Rule 6).
211212

212213
- Historical data repair MUST be a backfill definition that conforms to
213214
[data-backfills.md](data-backfills.md): stable ID, finite upper bound,
@@ -425,8 +426,9 @@ parity assertion on the table for that window.
425426
[thread-window-deployment.md](thread-window-deployment.md)) before applying
426427
the migration, which then verifies it. Frozen migrations `0076`, `0078` and
427428
`0081` predate this rule; the startup runner builds their indexes first
428-
(`INLINE_INDEX_BUILDS` in `crates/buzz-db/src/runtime/migration.rs`), and a
429-
source test rejects any other migration that refuses a populated table.
429+
(`INLINE_INDEX_BUILDS` in `crates/buzz-db/src/runtime/migration.rs`). A
430+
source test rejects any other migration that raises `'prebuild …'`; it
431+
matches that wording only, so review must catch other refusals.
430432
Partitioned parents need per-partition concurrent builds attached to an
431433
`ON ONLY` parent index.
432434
- The declarative schema source declares indexes with plain `CREATE INDEX`.

0 commit comments

Comments
 (0)