migrationpilot

MigrationPilot is a local static analysis tool for PostgreSQL migrations, positioned to block unsafe database changes before migration merge or execution by an agent. It runs without a database connection, uses PostgreSQL's own parser, checks 112 rules, and signals problems with a non-zero exit code in CI. The project is MIT-licensed and requires no account.

Main capabilities

• Rule checking: 112 built-in rules, of which 34 are critical level, 78 are warning level, and 20 can be auto-fixed with --fix. Rules adapt to --pg-version (Postgres 9 to 18), for example REINDEX CONCURRENTLY is supported starting from 12, DETACH PARTITION CONCURRENTLY starting from 14, and the native NOT NULL ... NOT VALID path starting from 18.
• Lock and sequence analysis: combines the lock types acquired by statements and rule hits to give a risk level (GREEN 0-24, YELLOW 25-49, RED 50-100). Sequence analysis can detect cumulative risk across multiple migration files. It can be adjusted with --lock-budget and --hot-table-threshold, disabled with --no-sequence, and set to blocking with --fail-on-sequence.
• Auto-fix: analyze --fix can rewrite 20 fixable violations in place.
• Multiple outputs: supports text (default), json, sarif, and markdown formats; --quiet outputs one gcc-style line per violation, and --verbose outputs pass/fail for each statement. SARIF can integrate with GitHub Code Scanning, VS Code, and IntelliJ.
• Configuration: zero configuration is the default behavior; check can automatically detect 14 frameworks and analyze them in their application order, including Flyway, Liquibase, Alembic, Django, Knex, Prisma, TypeORM, Drizzle, Sequelize, goose, dbmate, Sqitch, Rails, and Ecto. You can also use --framework to force specification, or use --from-command to receive output from other generators. It provides five presets: recommended (default), strict, ci, startup, and enterprise. It supports disabling rules with in-file comments, such as -- migrationpilot-disable MP001 or -- migrationpilot-disable-file MP001.

Usage

• Installation: requires Node 22 or later; the PostgreSQL parser is compiled in and requires no additional setup. Single-file executables for Linux, macOS, and Windows are also provided for each version. The Windows .exe is not code-signed, so downloads may trigger SmartScreen or browser warnings; you can verify it with the SHA256SUMS from the same version's release page. Under Windows Git Bash, paths in mount arguments are rewritten by MSYS, so you should use a Windows-style working directory.
• Exit codes: 0 means clean, 1 means warnings under --fail-on warning, and 2 means critical.
• AI coding agent integration: provides an MCP server with seven tools, the most core of which is check_before_apply, a pass/fail gate before an agent writes or executes DDL; its decisions are consistent with the CLI and it likewise parses .migrationpilotrc.yml. The Claude Code plugin pairs skills with a PreToolUse hook, blocking tool calls when the agent has not checked the migration; the hook intentionally uses a fail-open strategy: a missing installation, SQL that cannot be parsed, or a timeout lets the call through and prompts on stderr. Cursor and Copilot can be integrated by copying the integration files to the corresponding rules directory or instruction file.
• CI: the GitHub Action posts the report as a PR comment, fails the check on critical violations, and writes a SARIF file; an upload step can be added when Code Scanning is needed. A GitLab pipeline can run on merge requests involving migrations, retain the JSON report as an artifact, and annotate the MR diff via GitLab Code Quality. It can also be used through migrationpilot hook install installs pure git hooks and is compatible with Husky; if using the pre-commit framework, pay attention to handling core.hooksPath conflicts.

Use cases and limitations

• Applicable: checking the safety of PostgreSQL migrations in local development, code review, and CI, especially suitable for having AI agents perform risk interception before applying migrations, and for evaluating the sequential risk of multiple migrations across files.
• Limitations: when not connecting to a database, the parts of the risk score involving table size and query frequency are capped, and precise measurements cannot be given; using --database-url can enable a read-only connection to read pg_class, pg_stat_statements, and pg_stat_activity, without reading user data or executing DDL. --offline skips update checks and all network calls, and the tool has no telemetry.

Pricing and licensing

• The core checking functionality is free and unmetered: all 112 rules (including production-context-related rules), autofix, sequence analysis, simulate, all output formats, the GitHub Action, and the MCP server are available, with no account, no seat limits, no telemetry, and an MIT license.
• The Org plan is $499/year and provides unified policies across repositories, enforcement controls that developers cannot silently disable, JSONL audit logs for each check, and direct support from maintainers. Ed25519 license keys are verified on the client side, with no network calls. When no valid key is provided, the run will state that the policy was not applied, rather than silently passing.