用途:对数据库迁移做执行前的安全审查,属于 db-migration-safety 模块(M22,性能轴)。默认只读,只分析和解释,不运行迁移。
主要能力:解析原始 SQL 或 ORM 生成的迁移,识别数据库引擎并加载对应锁/重写规则;逐条语句分类锁级别(如 Postgres ACCESS EXCLUSIVE 与 SHARE UPDATE EXCLUSIVE、是否全程阻塞表)、是否触发表重写(随表规模放大)、可逆性(是否有干净的 down 迁移,或已单向丢失/强制转换数据)、破坏性与数据丢失操作(DROP COLUMN/TABLE、TRUNCATE、类型收窄、枚举值删除、不可逆转换)。结果按 schema/finding.schema.json 输出,含状态、严重度、证据(引用违规语句并脱敏)、复现方式与预期影响;破坏性且不可逆的迁移为 severity-5。行数与锁时长不臆造,量级仅按高/中/低分档。对高风险变更建议 expand-contract 分步:扩展(新增可空列/新表/双写)、迁移(分批在线回填)、收缩(切换约束、删除旧结构),每步独立可逆并标注锁级别。
使用方式:命令 /claude-db:migrate。参数两种形式:单文件 lint 为 <migration-file|migration-dir> [flags];diff 模式为 <from-schema> <to-schema> [flags],先运行 node scripts/schema-diff.mjs --from <from-schema> --to <to-schema> 生成 up/down 迁移,再按单文件方式分类。未给参数时需询问或指向项目迁移目录。
安全与限制:命令不会自行应用迁移,--apply 仅表示请求应用。任何被判定为数据丢失/破坏性的步骤需显式令牌握手:展示确切语句与不可逆后果,要求用户逐字输入受影响对象名(如 DROP TABLE orders 需输入 orders),不匹配即中止。实际写入仅交由 db-migration-writer 子代理,且须在握手之后。具体引擎规则、握手细节见 references/migration-safety.md。