MigrationPilot 是一款面向 PostgreSQL 迁移的本地静态检查工具，定位是在迁移合并或由代理执行之前，阻止不安全的数据库变更。它不依赖数据库连接即可运行，使用 PostgreSQL 自带的解析器，检查 112 条规则，并在 CI 中以非零退出码表示问题。项目采用 MIT 许可，无需账号。
主要能力
- 规则检查：内置 112 条规则，其中 34 条为 critical 级别，78 条为 warning 级别，20 条可通过 --fix 自动修复。规则会随 --pg-version（Postgres 9 到 18）自适应，例如从 12 开始支持 REINDEX CONCURRENTLY，从 14 开始支持 DETACH PARTITION CONCURRENTLY，从 18 开始支持原生的 NOT NULL ... NOT VALID 路径。
- 锁与序列分析：结合语句获取的锁类型和规则命中情况给出风险等级（GREEN 0-24，YELLOW 25-49，RED 50-100）。序列分析可跨多个迁移文件发现累积风险。可用 --lock-budget、--hot-table-threshold 调节，用 --no-sequence 关闭，用 --fail-on-sequence 设为阻断。
- 自动修复：analyze --fix 可就地重写 20 个可修复的违规项。
- 多种输出：支持 text（默认）、json、sarif、markdown 格式，--quiet 输出每个违规一行 gcc 风格，--verbose 输出每条语句的通过/失败。SARIF 可对接 GitHub Code Scanning、VS Code 和 IntelliJ。
- 配置：零配置为默认行为，check 可自动检测 14 种框架并按其应用顺序分析，包括 Flyway、Liquibase、Alembic、Django、Knex、Prisma、TypeORM、Drizzle、Sequelize、goose、dbmate、Sqitch、Rails、Ecto。也可用 --framework 强制指定，或用 --from-command 接收其他生成器的输出。提供 recommended（默认）、strict、ci、startup、enterprise 五种预设。支持文件内注释禁用规则，如 -- migrationpilot-disable MP001 或 -- migrationpilot-disable-file MP001。
使用方式
- 安装：需要 Node 22 或更高版本，PostgreSQL 解析器已编译内置，无需额外设置。各版本也提供 Linux、macOS、Windows 的单文件可执行文件。Windows 的 .exe 未做代码签名，下载时可能触发 SmartScreen 或浏览器警告，可用同版本发布页的 SHA256SUMS 校验。Windows Git Bash 下挂载参数中的路径会被 MSYS 重写，应使用 Windows 形式的工作目录。
- 退出码：0 表示干净，1 表示在 --fail-on warning 下有警告，2 表示 critical。
- AI 编程代理集成：提供 MCP 服务器，包含七个工具，其中最核心的是 check_before_apply，作为代理写入或执行 DDL 前的通过/失败门禁，其判定与 CLI 一致，并同样解析 .migrationpilotrc.yml。Claude Code 插件将技能与 PreToolUse 钩子配对，在代理未检查迁移时阻止工具调用；该钩子有意采用失败放行策略：安装缺失、SQL 无法解析或超时会让调用通过并在 stderr 提示。Cursor 和 Copilot 可通过复制集成文件到对应规则目录或指令文件来接入。
- CI：GitHub Action 会以 PR 评论形式发布报告，在 critical 违规时使检查失败，并写出 SARIF 文件；需要 Code Scanning 时可增加上传步骤。GitLab 流水线可在涉及迁移的合并请求上运行，保留 JSON 报告为制品，并通过 GitLab Code Quality 标注 MR 差异。也可通过 migrationpilot hook install 安装纯 git 钩子，并兼容 Husky；若使用 pre-commit 框架，则注意 core.hooksPath 冲突的处理。
适用场景与限制
- 适用：在本地开发、代码审查和 CI 中检查 PostgreSQL 迁移的安全性，尤其适合让 AI 代理在应用迁移前进行风险拦截，以及跨文件评估多迁移的顺序风险。
- 限制：不连接数据库时，风险评分中涉及表大小和查询频率的部分会被封顶，无法给出精确测量；使用 --database-url 可开启只读连接读取 pg_class、pg_stat_statements 和 pg_stat_activity，不读用户数据、不执行 DDL。--offline 会跳过更新检查和所有网络调用，工具无遥测。
收费与许可
- 核心检查功能免费且不计量：全部 112 条规则（包括生产上下文相关规则）、自动修复、序列分析、simulate、所有输出格式、GitHub Action 和 MCP 服务器均可用，无账号、无席位限制、无遥测，MIT 许可。
- Org 计划为 499 美元/年，提供跨仓库的统一策略、开发者无法静默禁用的强制控制、每次检查的 JSONL 审计日志，以及维护者直接支持。Ed25519 许可密钥在客户端校验，无网络调用。未提供有效密钥时，运行会说明策略未应用，而不是静默通过。
