When to use this
- Any schema migration (add/drop column, add constraint, change type, new index) before it runs against production.
- A migration will run against a large/hot table and needs a lock-behavior check.
- Not for reviewing the application code that uses the new schema -- scope to the migration itself.
The skill file
Copy this verbatim. It's written in the SKILL.md format (YAML frontmatter + markdown instructions) that Claude Code, and increasingly other agent tools, read directly.
--- name: schema-migration-reviewer description: Review a database schema migration for backward compatibility with currently-running old application code, locking behavior on large/hot tables, and reversibility. Use before running any migration against a shared or production database. --- # Schema Migration Reviewer ## Backward compatibility during rollout If deploys are rolling (old and new application code run simultaneously for a period), the migration must not break the *old* code: - **Dropping/renaming a column** old code still reads/writes: breaks immediately for old instances. Needs a multi-step migration (add new, dual-write, backfill, switch reads, THEN drop old -- across separate deploys). - **Adding a NOT NULL column with no default**: breaks old code's INSERTs that don't set it. Add with a default, or nullable first, backfill, then tighten. - **Changing a column's type** in an incompatible way for old code's serialization/deserialization assumptions. ## Locking and performance on large tables - Does this migration take a lock that blocks reads/writes for its duration (common for `ALTER TABLE` adding a column with a default on older database versions, or building an index without a "concurrent"/ "online" option)? On a large or high-traffic table, this can cause a production outage, not just a slow migration. - Prefer the database's non-blocking/concurrent variants (e.g. `CREATE INDEX CONCURRENTLY` in Postgres) for large tables where available. ## Reversibility - Does a `down`/rollback migration exist, and does it actually restore the prior state without data loss? A migration that drops a column has no data-preserving rollback by definition -- confirm that's accepted, not assumed. ## Output Findings on backward compatibility, locking risk, and reversibility, each with the specific concern and the safer alternative if one exists.
Installing it elsewhere
The frontmatter/body split above is Claude Code's convention. Here's how to carry the same instructions into other tools:
Save the file below verbatim (frontmatter included) at that path, project-local or in ~/.claude/skills/ for a user-level skill. Claude Code loads the name/description pair to decide when to pull it in, or you invoke it directly as /schema-migration-reviewer.
Convert the YAML frontmatter to Cursor's rule format (description, globs, alwaysApply: false) and keep the markdown body as the rule content. Cursor surfaces it by description match, same idea as Claude Code's auto-load.
Codex CLI (and increasingly other agentic CLIs) read AGENTS.md at the repo root as always-on instructions. Paste the markdown body under a heading like ## {title}; for GitHub Copilot's coding agent, the equivalent file is .github/copilot-instructions.md.
Append the markdown body to .windsurfrules at the repo root. Windsurf treats the whole file as always-on context, so keep only the instructions you want applied on every request.
- Approving a migration that drops/renames a column still used by the currently-deployed old code during a rolling release.
- Missing that an index build or ALTER TABLE will lock a large, high-traffic table without a non-blocking option enabled.
- Assuming a rollback migration is safe without checking it doesn't silently lose data.