db-migrations
Use when a schema change, DDL statement, or database migration is involved, including Supabase, Alembic, Prisma, or Drizzle, or when someone suggests the SQL editor, table editor, dashboard, psql, supabase db query, or execute_sql, including when the change is urgent.
- License 许可
- MIT
- 所属仓库
- sazlin/loadout
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- db-migrations
- description
- Use when a schema change, DDL statement, or database migration is involved, including Supabase, Alembic, Prisma, or Drizzle, or when someone suggests the SQL editor, table editor, dashboard, psql, supabase db query, or execute_sql, including when the change is urgent.
02 资源文件 1
- 参考文档evals/evals.json1.5 KB
03 SKILL.md 正文
Database migrations
The iron law
A schema change exists only as a migration file in the repo, applied by the project's migration runner, so the runner's history table records it.
Urgency does not create an exception. A request to skip the runner, paste SQL into a UI, or apply DDL outside the migration file is a refusal.
When to use
Use this skill before writing or applying any schema change.
Also use it when someone asks to:
- Paste SQL into the Supabase SQL editor or table editor
- Run DDL with
psql,supabase db query, or an MCPexecute_sqlcall - Apply SQL "just this once" and add the migration file later
- Ship a schema change faster by using the dashboard
Find the runner
Look in the repo before writing SQL. Collect every matching signal:
| Signal in the repo | Runner |
|---|---|
supabase/config.toml or supabase/migrations/ |
Supabase CLI |
alembic.ini |
Alembic |
prisma/migrations/ or a Prisma schema |
Prisma |
drizzle.config.ts or drizzle.config.js |
Drizzle |
Use the table only when exactly one signal matches. If more than one runner is present, use the migrate command and history table CI or the docs already use, including alembic upgrade head and alembic_version when that is what CI runs.
If none of these exist, search the repo for the command CI or the docs already use. If you still cannot find a runner, stop. Say what you looked for. Do not invent a runner. Do not fall back to a dashboard, a SQL editor, or a one-off database session.
Refusals
Refuse these, and refuse to recommend them to a human:
- Supabase SQL editor
- Supabase table editor, or any dashboard control that changes schema
psql, or any direct session, used to run DDLsupabase db queryused to run DDL- An MCP
execute_sqlcall, or an equivalent ad-hoc SQL tool, used to run DDL - Those same tools used for application-table
SELECT *, DML (INSERT,UPDATE,DELETE),COPY,GRANT/REVOKE, or pasted SQL that is not a catalog inspect
"Just this once", "I'll commit the file later", and "the dashboard is faster" are refusals.
Idempotent SQL (IF NOT EXISTS, or a DO block that checks pg_constraint) does not make those paths acceptable. The history table is the record. Re-runnable SQL hides drift.
Inspect schema from the migration files. If a live check is still needed, psql, supabase db query, and execute_sql may run only catalog or history inspects against information_schema, pg_catalog, supabase_migrations.schema_migrations, or alembic_version. Do not print connection strings, role passwords, or row contents from application tables.
Write the change
Read the current schema and the recent migration files before writing SQL.
Make the migration safe for data already deployed, and compatible with the application version still running during a rolling deploy.
Backfill remaining rows (WHERE <new_col> IS NULL) in bounded keyset batches (AND id > :last_id ORDER BY id LIMIT n). SET lock_timeout and statement_timeout for each backfill statement or session (the same helpers used before DDL), then COMMIT after each batch so row locks are not held for the full table, or use a follow-up job the repo already has. statement_timeout and lock_timeout abort a stuck statement; they do not replace per-batch commits or a job when the runner cannot COMMIT mid-file. If the runner cannot COMMIT mid-file, do not backfill in that migration; use the job. Stop when a batch updates zero rows. Do not loop UPDATE ... WHERE id IN (SELECT ... LIMIT n) without a remaining-row predicate. Put a destructive step, such as dropping a column or table, in a later migration, after the old application version is gone.
Set lock_timeout and statement_timeout before DDL so a blocked lock fails the migration instead of queueing forever.
Put CREATE INDEX CONCURRENTLY (or the runner's equivalent) in its own autocommit migration (autocommit_block, or apply without a wrapping transaction). CREATE INDEX CONCURRENTLY and DROP INDEX CONCURRENTLY cannot run inside a transaction. Do not put them in a transactional migration. Do not apply those short DDL timeouts to the concurrent build. Raise or disable lock_timeout and statement_timeout for that statement, then restore, or never SET the short DDL timeouts in that file. In the same autocommit file, run DROP INDEX CONCURRENTLY IF EXISTS for that index name immediately before CREATE INDEX CONCURRENTLY so a retry is unblocked when the failed version is not in the history table. If the build is cancelled, stop. Do not repair or skip the failed version, and do not loop db push. Use a later migration to drop the INVALID index only when the failed version was actually recorded.
Do not ADD COLUMN with a rewriting default on a live table. Add the column nullable, backfill in batches, then constrain. Follow skills/supabase-postgres-best-practices/references/lock-short-transactions.md. Do not invent a retry framework.
Avoid a lock that blocks writes for the whole table when a narrower statement exists. Add a test or a validation query for the new shape.
Supabase
Follow the Supabase migration guide.
- Create the file with
supabase migration newand a short name. Write the SQL only in that file. - Apply it locally with the command the repo already uses. If the repo does not document one, run
supabase migration upagainst the local database. Runsupabase db resetonly when the repo already uses it, or when the local database must be rebuilt. - Apply it to a linked or remote database only with
supabase db push, or the project's CI, from the migration file in the repo. Shared and remote databases get one apply. If CI or the repo's documented pipeline applies remotes, do not alsodb pushfrom the agent session.
If the runner fails, stop. Inspect supabase_migrations.schema_migrations. Do not re-run the migration SQL via psql or execute_sql. Do not supabase migration repair to skip a version that did not apply. Do not loop db push on failure.
The history table is supabase_migrations.schema_migrations.
Use supabase db pull and supabase migration repair only for schema that already existed before this task. That is discovered drift, not a way to ship a new change. If the remote database already has that pre-existing schema and it is not in supabase/migrations/, capture it with supabase db pull into a new migration file. Repair only the already-applied version on the database you pulled from. Do not db push that pulled version onto that same database. Do not use repair to skip a migration that has not been applied.
Do not add schema in the SQL editor, table editor, or dashboard in order to pull it. New DDL still goes through supabase migration new, then supabase migration up / supabase db push, or CI.
Alembic
Follow the Alembic tutorial.
- Create a revision with
alembic revision. Add--autogenerateonly when this repo already does. Write the upgrade in that revision file. - Apply it locally with
alembic upgrade head. - Apply it to any shared database with the project's documented Alembic command, from that revision file. Shared databases get one apply. If CI or the repo's documented pipeline applies remotes, do not also
alembic upgrade headfrom the agent session.
If the runner fails, stop. Inspect alembic_version. Do not re-run the revision SQL by hand. Do not loop alembic upgrade head on failure.
The history table is alembic_version. The same refusals apply. Do not run the revision's SQL by hand.
Prisma and Drizzle
Use the migration command the repo already runs (Prisma Migrate or Drizzle migrations). The same refusals apply. Do not invent flags the repo does not use.
Common rationalizations
| Excuse | Reality |
|---|---|
| "We're in a hurry" | The runner is how the change gets recorded. Out-of-band SQL becomes drift the next deploy trips over. |
| "Just this once" | One untracked change is enough for the next migration to fail or skip. |
| "I'll add the file later" | Later is how the history table and the repo diverge. Write the file first. |
| "The SQL editor runs the same SQL" | The editor does not write supabase_migrations.schema_migrations. The runner does. |
| "It's idempotent, so re-running is safe" | Idempotent SQL hides an unrecorded change. It does not record one. |
| "It's only a column" | A one-column change still goes through the runner. |
"execute_sql is fine for DDL" |
execute_sql is for catalog inspects, not schema changes or application rows. Schema changes go through the runner that records history. |
"I'll psql it and commit the file after" |
The database would change before the file exists. Create the file, then apply it. |
| "There is no runner, so use the dashboard" | Stop and say the runner is missing. Do not invent a dashboard path. |
Red flags
Stop if you are about to:
- Point a human at the Supabase SQL editor or table editor
- Paste migration SQL into a browser
- Run DDL, DML,
COPY,GRANT/REVOKE, or application-tableSELECT *throughpsql,supabase db query, orexecute_sql - Apply SQL to a remote database that is not in a migration file
- Use
supabase migration repairto skip a migration that has not run - Invent a migrate script the repo does not have
- Apply remotes from the agent and from CI against the same database
- Loop a failed
db pushoralembic upgrade head
04 同仓库更多 Skills
demo
Demo skill
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
verification-before-completion
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
using-superpowers
Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
using-git-worktrees
Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback