thealirazadev/migrate-guard

# migrate-guard 一款 CI linter，能够在危险的数据库迁移进入生产环境之前将其拦截。只需将其指向你的迁移文件——原生 SQL、Laravel 迁移 PHP 或 Django 迁移——它就会标记出那些会锁定热点表、重写数百万行数据，或在部署过程中导致运行中代码崩溃的操作。每个操作都包含一个稳定的规则代码、严重级别，并以可执行语句的形式明确给出安全替代方案。程序绝对不会执行任何代码：SQL 使用 sqlglot 解析，Django 文件使用 Python 的 `ast` 模块解析，Laravel 文件则使用有界正则表达式进行解析。 ## 存在的问题 一个通过了代码审查并在预发布环境中完美运行的迁移，仍然可能会导致生产环境崩溃：不带 `CONCURRENTLY` 的 `CREATE INDEX` 会在构建期间阻塞所有写操作；主动验证的外键在扫描时会锁定两张表；列重命名会在部署窗口期间破坏之前版本的应用程序；而且安全与不安全的界限会随着数据库版本的不同而变化（添加 `NOT NULL DEFAULT` 列在 Postgres 10 上会导致全表重写，而在 11+ 版本上仅仅是一个元数据变更）。审查人员无法将所有这些规则牢记于心；migrate-guard 将其编码为一个 CI 门禁，并具备值得信赖的、严格控制误报的能力。 ## 计划功能 - 九条规则，MG001-MG009：重写表和获取锁的 ALTER、非并发索引创建、没有默认值或数据回填的 NOT NULL 列、破坏性的删除（需要书面理由）、重命名、主动验证的外键、没有先创建并发索引的唯一约束、枚举值移除，以及 MySQL 上的 DDL/DML 混合操作。 - 方言和版本感知：支持 `postgres` 或 `mysql`，由 `postgres_version` 决定具体哪些操作具有危险性。能够识别安全形式且绝不将其标记。 - 将三种输入格式统一转换为单一的内部操作模型：原生 SQL、Laravel schema 构建器调用、Django 迁移操作——所有这些均无需执行任何代码即可提取。 - `.migrateguard.toml` 配置：方言、路径、忽略规则、带有强制书面理由的逐文件许可；以及用于针对特定位置豁免的内联允许注释。 - Diff-base 采用模式：仅对自某个 git ref 以来更改过的迁移文件进行 lint，因此拥有多年历史记录的代码库可以保持干净。 - 输出支持人类可读文本、JSON 或 GitHub 批注；通过退出代码控制 CI 门禁。 - 一个封装了 CLI 的复合 GitHub Action，提供感知 PR 的 diff-base 默认设置。 ## 技术栈 - Python 3.12 - sqlglot（SQL 解析），Click（CLI） - pytest，ruff，black；结合 uv 与已提交的 lockfile - 以 pip 包形式发布，并附带一个复合 GitHub Action ## 文档 | 文档 | 内容 | |---|---| | [docs/PRD.md](docs/PRD.md) | 问题、目标用户、核心功能、非目标、成功标准 | | [docs/architecture.md](docs/architecture.md) | 技术栈选型理由、组件、数据模型、规则目录、流程、故障模式、不变式 | | [docs/rules.md](docs/rules.md) | 项目专属工程规则 | | [docs/phases.md](docs/phases.md) | 实施阶段（包含提交记录和验证清单） | | [docs/design.md](docs/design.md) | CLI UX：输出布局、颜色、错误、退出代码 | | [docs/testing.md](docs/testing.md) | 测试策略、命令、CI 计划 | | [docs/api-contracts.md](docs/api-contracts.md) | CLI 命令、配置文件、允许语法、JSON schema、Action 输入 | | [docs/launch-checklist.md](docs/launch-checklist.md) | 发布前检查 | | [docs/memory.md](docs/memory.md) | 工作日志与决策 | ## 状态 本项目处于规划阶段：上述文档即为完整的规范说明，目前尚无实现代码。实现过程将严格按照 `docs/phases.md` 逐步进行，首先从原生 SQL pipeline 开始。此处描述的所有内容均为计划中的行为，而非已发布的行为。

标签：安全规则引擎, 数据库迁移, 逆向工具, 错误基检测, 静态代码分析