mickelsamuel/migrationpilot

**Block unsafe Postgres migrations before merge.**
Local, deterministic analysis for PostgreSQL migrations. Uses PostgreSQL's parser, checks 112 rules, and exits non-zero in CI. No account required. MIT.
Try it in your browser · GitHub Action · Documentation
Benchmark
| Tool | Strict detection | False positives |
|---|---:|---:|
| **MigrationPilot** | **31/33 (93.9%)** | **1/17 (5.9%)** |
| Squawk | 20/33 (60.6%) | **1/17 (5.9%)** |
| pgfence | 25/33 (75.8%) | 3/17 (17.6%) |
56 labelled files. Author-built corpus. Tools pinned.
Methodology · Corpus · What MigrationPilot missed · Reproduce: pnpm build && node bench/run.mjs
A finding
Exit code is 2. The Risk column combines what a statement's lock does with what the rules found in it, so a statement carrying a critical violation reads RED whatever its lock costs. The lock half of that is capped without a database connection — table size and query frequency need one. See Production context.
Contents
Install · AI coding agents · CI · What it checks · Beyond one file · Configuration · Output · Production context · Comparison · Pricing · Architecture · API
Install
Node 22 or newer. The PostgreSQL parser ships compiled in, so there is nothing else to set up. Exit codes are the same everywhere: 0 clean, 1 warnings under --fail-on warning, 2 critical.
Packaged builds land with each release, including single-file executables for Linux, macOS and Windows on the release page for machines without Node. The Windows .exe is not code-signed, so SmartScreen and most browsers will warn about it on download — SHA256SUMS on the same release is how you check you got the file we published, not a signature.
On Windows in Git Bash, MSYS rewrites paths inside the mount flag, so use the Windows-form working directory instead:
AI coding agents
Agents write migrations now. They are good at SQL and bad at knowing which statement takes an ACCESS EXCLUSIVE lock on a table with 40 million rows, and by then the outage has already happened.
**MCP server.** Seven tools, the important one being check_before_apply: a pass/fail gate the agent calls before it writes or runs DDL. It resolves your .migrationpilotrc.yml exactly like the CLI does, so its verdict is the verdict CI will give.
| Tool | Purpose |
|---|---|
| check_before_apply | {sql, pgVersion?, configPath?} returns {verdict: pass\|fail, failOn, violations[], summary} |
| analyze_migration | Violations, risk score and lock analysis for one migration |
| analyze_migration_dir | Per-file results plus an aggregate for a whole folder |
| get_rule | What a rule reports, why it matters, whether it auto-fixes |
| suggest_fix | Auto-fixed SQL plus the violations that need a human |
| explain_lock | The lock one DDL statement takes and what it blocks |
| list_rules | The full catalogue |
**Claude Code plugin.** integrations/claude-code/ pairs a skill that tells Claude to check migrations with a PreToolUse hook that blocks the tool call when it doesn't. It fails open on purpose: a missing install, unparseable SQL, or a timeout lets the call through with a note on stderr, because a guardrail that breaks your workflow when it can't run gets uninstalled.
**Cursor and Copilot.** Copy integrations/cursor/migrationpilot.mdc into .cursor/rules/, or paste integrations/copilot/copilot-instructions-snippet.md into .github/copilot-instructions.md. Both tell the agent when to run MigrationPilot and that suppressing a rule to get past a violation is the user's call, not the agent's.
CI
GitHub Action
Posts a report as a PR comment, fails the check on critical violations, and writes a SARIF file. To feed it into Code Scanning, add an upload step (needs Advanced Security on private repos):
Without the permissions block the Action still runs. It warns, analyzes every file matching the glob instead of only the ones the PR changed, and skips the comment. The check verdict, the SARIF file and the inline annotations come from the analysis either way.