| name | db-migrations |
| description | Generate, review, and apply PostgreSQL database migrations for this repository using Drizzle. Use when Codex changes schema files under `packages/db/src/control-plane/schema` or `packages/db/src/data-plane/schema`, needs to add or inspect migrations under `packages/db/migrations`, needs to run either the control-plane or data-plane migration runner exposed by the app packages, or is asked how database migrations work in this repo. |
Db Migrations
Follow the repo's database migration workflow exactly. Keep migration generation schema-first, let Drizzle write migration artifacts, and apply them through the app scripts for the matching plane.
Workflow
- Determine which plane the migration belongs to.
Use
control-plane for schema changes under packages/db/src/control-plane/schema/** and migration files under packages/db/migrations/control-plane/**.
Use data-plane for schema changes under packages/db/src/data-plane/schema/** and migration files under packages/db/migrations/data-plane/**.
- Make schema changes first in the matching schema directory.
- Generate the migration from the repository root with Drizzle and always provide a descriptive kebab-case name.
For control-plane:
pnpm --filter @mistle/db exec drizzle-kit generate --config packages/db/drizzle.control-plane.config.ts --name add-descriptive-change-name
For data-plane:
pnpm --filter @mistle/db exec drizzle-kit generate --config packages/db/drizzle.data-plane.config.ts --name add-descriptive-change-name
- Review the generated files in the matching
packages/db/migrations/<plane>/ directory.
Expect a new NNNN_<descriptive-kebab-name>.sql, a new meta/*_snapshot.json, and an updated meta/_journal.json.
- Apply the migration through the matching app script.
For control-plane:
pnpm --filter @mistle/control-plane-api db:migrate
For data-plane:
pnpm --filter @mistle/data-plane-api db:migrate
Rules
- Generate migrations only with
drizzle-kit.
- Migrations must be named. Pass
--name and use a short descriptive kebab-case name that matches the schema change.
- Never handwrite migration SQL,
meta/_journal.json, or snapshot files.
- Use the migration application script exposed by the matching app package; do not bypass it with an ad hoc runner for normal migration tasks.
- If the migrator reports a missing journal file, generate the migration first instead of trying to patch migration metadata manually.
- Prefer adding a new migration over rewriting committed migration history. Only edit historical migrations when the user explicitly asks.
Validation
Run the smallest relevant checks for the migration change:
For control-plane changes:
pnpm --filter @mistle/control-plane-api typecheck
For data-plane changes:
pnpm --filter @mistle/data-plane-api typecheck
If the change adds or modifies migration SQL files, also run the existing Squawk-backed SQL lint command:
pnpm lint:sql
pnpm lint:sql is the repo alias for pnpm --filter @mistle/db lint:sql.
Run broader repo checks when the task changes more than migration artifacts or when the user asks for full verification.
