Community写作与编辑github.com

安全迁移

在数据库迁移锁定表之前及时发现并阻止它。一个 Claude Agent 技能,用于审查迁移中的停机风险,并将其重写为安全、零停机的步骤。支持 PostgreSQL 和 MySQL,兼容任何框架。

安全迁移 是什么?

“安全迁移”技能旨在帮助开发者和 AI Agent 用户审查数据库迁移方案,识别并规避可能导致生产环境停机的风险。该技能能够分析 PostgreSQL 和 MySQL(包括 MariaDB)的迁移文件,标记出诸如添加带默认值的列、设置 NOT NULL、创建索引等常见的高风险操作,这些操作可能会获取 ACCESS EXCLUSIVE 锁或导致全表重写,从而阻塞所有读写操作。技能的核心工作流程包括:建立上下文(识别数据库引擎、版本和框架)、定位并分类每个操作的风险等级(不安全、需谨慎、安全),然后为每个不安全或需谨慎的操作提供具体的风险说明、安全的 SQL 重写方案(包括并发索引、NOT VALID 约束等)以及配套的部署序列(如扩展/收缩模式)。此外,技能还能根据不同框架(如 Rails)提供可运行的惯用重写代码。最终输出一份结构化的审查报告,包含每个文件的风险评估、安全重写步骤和整体摘要,帮助团队在迁移上线前消除隐患。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add windchillscalanthes-ship-it/safe-migrations

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

安全迁移 是做什么的?

捕获那些静默锁定表或在磁盘上重写表的模式更改,并在它们进入生产环境之前将其转变为安全、零停机的迁移。

一行看似无害的代码(SET NOT NULL、CREATE INDEX、ADD FOREIGN KEY、带有 DEFAULT 的列)可能会获取 ACCESS EXCLUSIVE 锁或强制全表重写。在一个庞大且繁忙的表上,这意味着所有读写操作都将排队等待迁移完成——从而导致服务中断。本技能可以审查迁移,精确解释什么会锁定以及为什么,并生成安全的重写方案。

何时使用

  • 你正在编写一个新的迁移,并希望在提交前进行审查。
  • 你正在审查 PR/diff 中的迁移。
  • 你即将对一个已有行的表执行迁移。
  • 有人问“这个迁移安全吗?”、“这会锁表吗?”或“如何零停机地完成这个操作?”。

如果目标表是空的或非常小(在同一迁移中创建的新表、只有少量行的配置表),那么大多数这些风险都不适用——请说明情况,不要过度设计。

工作流程

  1. 建立上下文。 确定数据引擎(是 PostgreSQL 还是 MySQL/MariaDB,如果可以,请确定主版本号)和框架。版本很重要:某些操作在 Postgres 11/12+ 上是安全的,但在更早的版本上则不是。如果版本未知,请标记那些安全性依赖于版本的操作。

  2. 定位操作。 读取每个迁移文件,并列出它执行的每个模式或数据操作。一个迁移常常包含多个操作。

  3. 对照下面的风险目录对每个操作进行分类。分配一个严重级别:

    • 🔴 不安全 —— 将获取阻塞锁、重写表或破坏正在运行的应用程序版本。必须重写。
    • 🟡 谨慎 —— 仅在特定条件下安全(小表、特定引擎版本、低流量、正确设置)。请注明该条件。
    • 🟢 安全 —— 仅元数据操作或其他非阻塞操作。无需更改。
  4. 重写不安全的部分。 对于每个 🔴/🟡,给出:

    • 具体风险(哪个锁、阻塞什么、大致影响),
    • 一个安全重写方案,作为可运行的步骤(SQL 以及,如果使用了框架,则提供惯用的框架代码),以及
    • 当应用程序代码必须同步更改时的部署序列(参见下面的 扩展/收缩)。
  5. 使用底部的输出模板生成报告。首先列出不安全的项目。

对于引擎和框架特定的深度信息,按需加载参考文件:

  • reference/postgres.md —— PostgreSQL 的锁、版本和安全重写(最详细)。
  • reference/mysql.md —— MySQL/MariaDB 的在线 DDL、ALGORITHM/LOCK、gh-ost。
  • reference/patterns.md —— 引擎无关的模式:扩展/收缩、批量回填、lock_timeout、N-1 兼容性。
  • reference/frameworks.md —— 如何在每个框架中表达并发索引、禁用 DDL 事务以及拆分状态与模式。

请阅读与你当前面对的迁移相关的参考文件,而不是猜测版本特定的行为。

风险目录(高频问题)

以 Postgres 为中心;MySQL 的差异在 reference/mysql.md 中说明。“重写” = 整个表在磁盘上被复制;“扫描” = 完全读取表;两者都在锁定状态下进行,该锁会阻塞并发流量。

#操作为何危险安全方法
1带 DEFAULT 添加列易变默认值(例如 gen_random_uuid()、random())会在 ACCESS EXCLUSIVE 下重写表。在 Postgres < 11 上,任何默认值都会重写。先添加可空且无默认值的列 → ALTER … SET DEFAULT(仅影响新行)→ 分批回填现有行 → 添加 NOT NULL(第 2 行)。
2在已有列上**SET NOT NULL**在 ACCESS EXCLUSIVE 下全表扫描以验证没有空值——阻塞读写。添加 CHECK (col IS NOT NULL) NOT VALID → VALIDATE CONSTRAINT(非阻塞)→ SET NOT NULL(Postgres 12+ 重用已验证的检查并跳过扫描)→ 可选地删除该检查。
3CREATE INDEX(非并发)在整个构建过程中持有 SHARE 锁,阻塞写入。CREATE INDEX CONCURRENTLY —— 必须在事务外部运行;如果失败可能会留下一个 INVALID 索引(删除并重试)。
4DROP INDEX对表持有 ACCESS EXCLUSIVE 锁。DROP INDEX CONCURRENTLY(Postgres 9.2+)。
5添加 FOREIGN KEY锁定两个表并扫描子表以验证现有行。添加 NOT VALID 约束(快速,无扫描)→ 在单独的步骤中 VALIDATE CONSTRAINT(仅获取 SHARE UPDATE EXCLUSIVE)。
6添加 UNIQUE 约束在阻塞锁下构建唯一索引。CREATE UNIQUE INDEX CONCURRENTLY → ALTER TABLE … ADD CONSTRAINT … UNIQUE USING INDEX <name>(附加现有索引,快速)。
7添加 CHECK 约束在 ACCESS EXCLUSIVE 下扫描表。ADD CONSTRAINT … CHECK (…) NOT VALID → VALIDATE CONSTRAINT。
8ALTER COLUMN … TYPE通常会在 ACCESS EXCLUSIVE 下重写表及其索引。(例外:放宽/删除 varchar 长度限制是纯元数据操作。)扩展/收缩:添加新列,双写 + 回填,切换读取,删除旧列。
9重命名字段/表DDL 是瞬间完成的,但一旦提交就会破坏正在运行的应用程序版本。绝不在生产环境中原地重命名。扩展/收缩:添加新名称,双写,回填,切换读取,删除旧名称——跨越两次部署。
10DROP COLUMN仍在引用它的应用程序代码(包括 SELECT *)会出错;数据丢失(难以回滚)。仅限收缩阶段:首先部署停止使用该列的应用程序代码,然后在后续迁移中删除。
11在单个大 UPDATE 中回填长时间运行的事务 → 锁竞争、表膨胀、复制延迟。按主键范围分批处理,每批之间提交;保持每批简短。在模式迁移之外执行。
12没有设置 lock_timeout / statement_timeout即使是瞬间的 DDL 也需要短暂的 ACCESS EXCLUSIVE 锁。如果它在长时间查询之后排队,它会阻塞之后到达的每个查询——导致级联停滞。在 DDL 之前设置一个较低的 lock_timeout(和 statement_timeout),使迁移快速失败而不是让整个站点宕机。

指导原则

  • 扩展/收缩(并行更改)。 任何不向后兼容的更改都必须拆分,以使数据库在发布期间同时兼容旧和新应用程序版本。扩展(添加,向后兼容) → 迁移数据/双写 → 收缩(删除)——通常跨越两次或更多次部署。这是重命名、类型更改、拆分和合并的基石。
  • 每个迁移只做一个逻辑更改。 更易于审查、推理和回滚。永远不要在同一个事务中混合模式更改和大数据回填。
  • N-1 兼容性。 在部署期间,应用程序的两个版本同时运行。模式必须服务于两者。
  • 将模式与数据分开。 结构化的 DDL 和行回填补属于不同的步骤(通常在不同的部署中)。
  • 建议要适度。 空的/很小的/全新的表不需要这些。当表只有 12 行时,不要将两行更改变成五步操作。

输出模板

## 迁移安全审查

**引擎:** <例如 PostgreSQL 14>  ·  **框架:** <例如 Rails>  ·  **审查的文件数:** <n>

### 🔴 <文件> —— 不安全
**操作:** <它做什么>
**风险:** <哪个锁/重写,它阻塞什么>
**可能的影响:** <例如 "对 `users` 表的全表扫描期间持有全局锁;在 4000 万行的表上,阻塞流量持续数秒到数分钟">
**安全重写:**
<可运行的步骤——SQL 和/或框架代码>
**部署序列:** <仅当应用程序代码必须同步更改时>

### 🟡 <文件> —— 谨慎
**操作/风险/条件/建议**

### 🟢 <文件> —— 安全
<一行:为什么安全,无需操作>

---
**总结:** <n 不安全,n 谨慎,n 安全。> <一行结论。>

始终提供用户可以直接复制并运行的安全重写方案——而不仅仅是做什么的描述。

相关技能