migrate

/claude-db:migrate

迁移安全 lint，由模块 db-migration-safety (M22, axis performance) 通过 db-migration-safety / MSA 检查负责。默认模式为只读：它会分析并说明，但不会运行迁移。

$ARGUMENTS 有两种形式：

• 单文件 lint — <migration-file|migration-dir> [flags]：解析并分类现有迁移（见下文）。
• diff 模式 — <from-schema> <to-schema> [flags]：两个 schema 路径。运行 node scripts/schema-diff.mjs --from <from-schema> --to <to-schema> 生成 up/down 迁移，然后按照单文件模式中的相同方式分类生成的迁移。

如果没有提供参数，请询问参数（或指出项目的迁移目录）。

Diff 模式（<from-schema> <to-schema>）

1. 运行 node scripts/schema-diff.mjs --from <A> --to <B> 生成 up 和 down 迁移；schema-diff.mjs 会标记破坏性步骤。
2. 向用户展示生成的 up/down 迁移，并以通俗语言概述每个步骤。
3. 在写入任何内容前，先按下文的数据丢失握手流程处理 schema-diff.mjs 标记为破坏性的每个步骤（DROP TABLE/COLUMN、类型收窄）。
4. 然后按照单文件模式中相同的锁、重写和可逆性分析，对生成的迁移进行分类。

操作步骤（单文件 lint）

1. 解析迁移（原始 SQL 或生成的 ORM 迁移）。检测数据库引擎；加载对应引擎的锁和重写规则。
2. 对每条语句进行分类：
   • 锁级别 — 例如，Postgres ACCESS EXCLUSIVE（阻止读写）与 SHARE UPDATE EXCLUSIVE；以及它是否会在整个操作期间锁住表。
   • 表重写 — 此更改是否会重写每一行（例如，在旧版引擎上添加带有易变默认值的 NOT NULL 列，或更改列类型）？重写成本会随表大小增加。
   • 可逆性 — 是否有干净的 down 迁移，还是只能单向执行（数据已被删除或强制转换）？
   • 破坏性 / 数据丢失 — DROP COLUMN/TABLE、TRUNCATE、类型收窄、枚举值移除、不可逆的强制转换。
3. 按照 schema/finding.schema.json 输出发现项（status/severity/引用违规语句并对机密信息脱敏的 evidence.observed/verification.reproduce/expected_impact.axis=performance+置信度+影响程度）。不可逆且没有 expand-contract 的破坏性迁移，严重性为 5（限制 Performance 上限）。绝不编造行数或锁定时长——影响程度按高|中|低分级，并根据描述的表大小评估，不得凭空捏造。
4. 为存在风险的更改提出 expand-contract 部署方案：expand（添加新的可空列 / 新表 / 双写）、migrate（分批在线回填）、contract（切换约束、删除旧结构）——每一步单独执行且各自可逆，并注明每一步的锁级别。

安全 / 握手流程

• 此命令绝不会自行应用迁移。--apply 仅表示请求应用。
• 任何被归类为数据丢失 / 破坏性的步骤都必须进行明确的令牌握手：展示确切语句和不可逆后果，然后要求用户逐字输入受影响对象的名称——不能只回答是或否。例如，要确认 DROP TABLE orders，用户必须输入 orders；要删除 email 列，用户必须输入 email。如果回复与对象名称不完全匹配，则中止该步骤。握手规则见 references/migration-safety.md。
• 实际写入只能委托给 db-migration-writer 子 Agent（唯一拥有 Write/Edit 权限的 Agent），且必须在握手完成后进行。默认只读。