Framework stores
Every framework table in packages/core/src is owned by exactly one
defineStore() from src/db/store-registry.ts. The release step applies a
store's migrations once per database and records each in
_an_store_migrations, then verifies the ledger covers every registered store.
Hosted functions of release-owned apps do no schema work at all. Design and
rollout:
docs/plans/2026-09-28-store-registry-schema-ownership.md.
App-owned template tables are not covered here; they use runMigrations or
Drizzle (see storing-data).
Rules
- Schema lives in a store's migration list, nowhere else. No
let _initPromise memo, no ensureTableExists / ensureColumnExists /
ensureIndexExists and no CREATE/ALTER outside a defineStore()
migration. Keep the module's exported ensure*() as
return xStore.ready(); so callers do not change.
- Append, never edit. A database records a migration by name and never runs
it again, so editing, renaming, reordering or deleting one never reaches
databases that already applied it. To change a table, add a new named
migration at the end.
store-migrations.lock.json makes this a CI failure.
- Baselines converge only tables that never recorded them. A database with
no ledger row for the baseline runs it against whatever shape it has, so keep
CREATE TABLE IF NOT EXISTS plus ensureColumnExists for every column ever
added. Never squash a baseline into today's CREATE TABLE. Where the ledger
is read (local, self-hosted, the release step), a database that recorded the
baseline, such as every snapshot install, never runs it again, and local
runtimes never run release-only list entries, so a new column also needs its
own appended migration.
- Idempotent and additive. First runs can race and old functions keep
serving during a release. New columns are nullable or defaulted.
- One store's tables only, or say so. Stores apply in registry order (by
id). A migration that reads or alters another store's tables needs
after: ["other_store_id"] on its store; the release pass fails on an
unknown id or a cycle.
- Folding a
runMigrations list. Append it whole with
...fromMigrationEntries(TABLE, LIST, { data: [...] }) to the store that
owns its tables. Each entry keeps its old identity, so databases that
applied it import it instead of re-running it. A release-only list keeps
running only in the release step; pass { ranAtBoot: true } for a list that
also ran at plugin boot, so local runtimes import its history and hosted
apps without release migrations keep its old bookkeeping. Never rename or
reorder the entries.
- Mark data migrations. Backfills and seeds get
kind: "data"; a schema
snapshot cannot replace them.
- Never swallow a failure inside a migration. The ledger would record it as
applied and it would never retry. Rethrow at release
(
isMigrationAuthorizedRuntime()), as widenIntColumnsToBigInt does.
releaseOnly: true for a store a request must never create, even in
hosted apps that do not migrate at release.
- Literal declaration. Write
export const xStore = defineStore({ id: "snake_case_id", migrations: [...] }); the generator only reads that form,
and the guard fails on any other. Ids are permanent.
Adding or changing a store
export const widgetsStore = defineStore({
id: "widgets",
migrations: [
{
name: "baseline",
run: async () => {
await ensureTableExists("widgets", CREATE_WIDGETS_SQL);
await ensureColumnExists("widgets", "owner", `ALTER TABLE widgets ADD COLUMN IF NOT EXISTS owner TEXT`);
},
},
{ name: "owner-index", sql: `CREATE INDEX IF NOT EXISTS widgets_owner_idx ON widgets (owner)` },
{ name: "backfill-owner", kind: "data", sql: `UPDATE widgets SET owner = created_by WHERE owner IS NULL` },
],
});
export function ensureWidgetsTable(): Promise<void> {
return widgetsStore.ready();
}
Then run, in this order:
pnpm gen:store-registry — rewrites store-registry.generated.ts and
store-migrations.lock.json. Then pnpm gen:schema-snapshot — rewrites
schema-snapshot.generated.ts, the schema fresh databases install in one
step. Commit all three; release-schema.snapshot.spec.ts fails when the
snapshot no longer covers every schema migration.
pnpm guard:release-schema-complete and pnpm guard:additive-migrations.
- The store's own spec, plus
src/db/store-registry.spec.ts,
src/server/release-schema.cold-start.spec.ts and
src/server/release-schema.upgrade.spec.ts from packages/core. The
upgrade spec replays an older release's schema and fails when your change
does not reach existing databases (for example a column added only to a
CREATE TABLE).
Readiness modes
ready() picks a mode from who owns the schema:
- apply — the release step (
withMigrationRuntime, under a lease in
_an_store_migration_lock, verifying the ledger against the registry
afterwards), plus local dev, tests and self-hosted Node. Each migration runs
once per database. Specs that mock getDbExec answer ledger statements with
db/store-ledger.test-helpers.ts.
- trust — hosted function of an app that migrates at release. No schema
work at all, not even a ledger read.
- hosted-replay — hosted apps without release migrations. Runs migrations
idempotently, as before, and never writes the ledger: previews share
production's database and request writes can roll back.
SchemaNotMigratedError is raised by the release step when the ledger does
not cover the code being shipped. It fails that deploy; fix the migration or
the deploy, never catch it. Code that catches everything around a store query
must fail closed for security reads (revocation, budgets, access): a missing
table must never read as allowed or empty.
Reviewed exceptions
// guard:allow-unreleased-schema — <reason> exempts a module from schema
placement checks. Current exceptions: sharing/indexes.ts (indexes app and
framework share tables at release) and triggers/event-queue.ts (owned by a
versioned list until those fold into stores). A new one needs a reason a
reviewer can check.
1---2name: framework-stores3description: >-4 How framework-owned tables in packages/core declare and change their schema5 with defineStore(). Use before adding a table, column, index, backfill or6 seed to a core store, before writing an ensure*Table() function, and when7 guard:release-schema-complete or SchemaNotMigratedError fires.8scope: dev9metadata:10 source: https://skillmd.com/skills/builderio/framework-stores11 internal: true12---1314# Framework stores1516Every framework table in `packages/core/src` is owned by exactly one17`defineStore()` from `src/db/store-registry.ts`. The release step applies a18store's migrations once per database and records each in19`_an_store_migrations`, then verifies the ledger covers every registered store.20Hosted functions of release-owned apps do no schema work at all. Design and21rollout:22`docs/plans/2026-09-28-store-registry-schema-ownership.md`.2324App-owned template tables are not covered here; they use `runMigrations` or25Drizzle (see `storing-data`).2627## Rules2829- **Schema lives in a store's migration list, nowhere else.** No30 `let _initPromise` memo, no `ensureTableExists` / `ensureColumnExists` /31 `ensureIndexExists` and no `CREATE`/`ALTER` outside a `defineStore()`32 migration. Keep the module's exported `ensure*()` as33 `return xStore.ready();` so callers do not change.34- **Append, never edit.** A database records a migration by name and never runs35 it again, so editing, renaming, reordering or deleting one never reaches36 databases that already applied it. To change a table, add a new named37 migration at the end. `store-migrations.lock.json` makes this a CI failure.38- **Baselines converge only tables that never recorded them.** A database with39 no ledger row for the baseline runs it against whatever shape it has, so keep40 `CREATE TABLE IF NOT EXISTS` plus `ensureColumnExists` for every column ever41 added. Never squash a baseline into today's `CREATE TABLE`. Where the ledger42 is read (local, self-hosted, the release step), a database that recorded the43 baseline, such as every snapshot install, never runs it again, and local44 runtimes never run release-only list entries, so a new column also needs its45 own appended migration.46- **Idempotent and additive.** First runs can race and old functions keep47 serving during a release. New columns are nullable or defaulted.48- **One store's tables only, or say so.** Stores apply in registry order (by49 id). A migration that reads or alters another store's tables needs50 `after: ["other_store_id"]` on its store; the release pass fails on an51 unknown id or a cycle.52- **Folding a `runMigrations` list.** Append it whole with53 `...fromMigrationEntries(TABLE, LIST, { data: [...] })` to the store that54 owns its tables. Each entry keeps its old identity, so databases that55 applied it import it instead of re-running it. A release-only list keeps56 running only in the release step; pass `{ ranAtBoot: true }` for a list that57 also ran at plugin boot, so local runtimes import its history and hosted58 apps without release migrations keep its old bookkeeping. Never rename or59 reorder the entries.60- **Mark data migrations.** Backfills and seeds get `kind: "data"`; a schema61 snapshot cannot replace them.62- **Never swallow a failure inside a migration.** The ledger would record it as63 applied and it would never retry. Rethrow at release64 (`isMigrationAuthorizedRuntime()`), as `widenIntColumnsToBigInt` does.65- **`releaseOnly: true`** for a store a request must never create, even in66 hosted apps that do not migrate at release.67- **Literal declaration.** Write `export const xStore = defineStore({ id:68 "snake_case_id", migrations: [...] })`; the generator only reads that form,69 and the guard fails on any other. Ids are permanent.7071## Adding or changing a store7273```ts74export const widgetsStore = defineStore({75 id: "widgets",76 migrations: [77 {78 name: "baseline",79 run: async () => {80 await ensureTableExists("widgets", CREATE_WIDGETS_SQL);81 await ensureColumnExists("widgets", "owner", `ALTER TABLE widgets ADD COLUMN IF NOT EXISTS owner TEXT`);82 },83 },84 { name: "owner-index", sql: `CREATE INDEX IF NOT EXISTS widgets_owner_idx ON widgets (owner)` },85 { name: "backfill-owner", kind: "data", sql: `UPDATE widgets SET owner = created_by WHERE owner IS NULL` },86 ],87});8889export function ensureWidgetsTable(): Promise<void> {90 return widgetsStore.ready();91}92```9394Then run, in this order:95961. `pnpm gen:store-registry` — rewrites `store-registry.generated.ts` and97 `store-migrations.lock.json`. Then `pnpm gen:schema-snapshot` — rewrites98 `schema-snapshot.generated.ts`, the schema fresh databases install in one99 step. Commit all three; `release-schema.snapshot.spec.ts` fails when the100 snapshot no longer covers every schema migration.1012. `pnpm guard:release-schema-complete` and `pnpm guard:additive-migrations`.1023. The store's own spec, plus `src/db/store-registry.spec.ts`,103 `src/server/release-schema.cold-start.spec.ts` and104 `src/server/release-schema.upgrade.spec.ts` from `packages/core`. The105 upgrade spec replays an older release's schema and fails when your change106 does not reach existing databases (for example a column added only to a107 `CREATE TABLE`).108109## Readiness modes110111`ready()` picks a mode from who owns the schema:112113- **apply** — the release step (`withMigrationRuntime`, under a lease in114 `_an_store_migration_lock`, verifying the ledger against the registry115 afterwards), plus local dev, tests and self-hosted Node. Each migration runs116 once per database. Specs that mock `getDbExec` answer ledger statements with117 `db/store-ledger.test-helpers.ts`.118- **trust** — hosted function of an app that migrates at release. No schema119 work at all, not even a ledger read.120- **hosted-replay** — hosted apps without release migrations. Runs migrations121 idempotently, as before, and never writes the ledger: previews share122 production's database and request writes can roll back.123124`SchemaNotMigratedError` is raised by the release step when the ledger does125not cover the code being shipped. It fails that deploy; fix the migration or126the deploy, never catch it. Code that catches everything around a store query127must fail closed for security reads (revocation, budgets, access): a missing128table must never read as allowed or empty.129130## Reviewed exceptions131132`// guard:allow-unreleased-schema — <reason>` exempts a module from schema133placement checks. Current exceptions: `sharing/indexes.ts` (indexes app and134framework share tables at release) and `triggers/event-queue.ts` (owned by a135versioned list until those fold into stores). A new one needs a reason a136reviewer can check.