安全迁移 是做什么的?
捕获那些静默锁定表或在磁盘上重写表的模式更改,并在它们进入生产环境之前将其转变为安全、零停机的迁移。
一行看似无害的代码(SET NOT NULL、CREATE INDEX、ADD FOREIGN KEY、带有 DEFAULT 的列)可能会获取 ACCESS EXCLUSIVE 锁或强制全表重写。在一个庞大且繁忙的表上,这意味着所有读写操作都将排队等待迁移完成——从而导致服务中断。本技能可以审查迁移,精确解释什么会锁定以及为什么,并生成安全的重写方案。
何时使用
- 你正在编写一个新的迁移,并希望在提交前进行审查。
- 你正在审查 PR/diff 中的迁移。
- 你即将对一个已有行的表执行迁移。
- 有人问“这个迁移安全吗?”、“这会锁表吗?”或“如何零停机地完成这个操作?”。
如果目标表是空的或非常小(在同一迁移中创建的新表、只有少量行的配置表),那么大多数这些风险都不适用——请说明情况,不要过度设计。
工作流程
-
建立上下文。 确定数据引擎(是 PostgreSQL 还是 MySQL/MariaDB,如果可以,请确定主版本号)和框架。版本很重要:某些操作在 Postgres 11/12+ 上是安全的,但在更早的版本上则不是。如果版本未知,请标记那些安全性依赖于版本的操作。
-
定位操作。 读取每个迁移文件,并列出它执行的每个模式或数据操作。一个迁移常常包含多个操作。
-
对照下面的风险目录对每个操作进行分类。分配一个严重级别:
- 🔴 不安全 —— 将获取阻塞锁、重写表或破坏正在运行的应用程序版本。必须重写。
- 🟡 谨慎 —— 仅在特定条件下安全(小表、特定引擎版本、低流量、正确设置)。请注明该条件。
- 🟢 安全 —— 仅元数据操作或其他非阻塞操作。无需更改。
-
重写不安全的部分。 对于每个 🔴/🟡,给出:
- 具体风险(哪个锁、阻塞什么、大致影响),
- 一个安全重写方案,作为可运行的步骤(SQL 以及,如果使用了框架,则提供惯用的框架代码),以及
- 当应用程序代码必须同步更改时的部署序列(参见下面的 扩展/收缩)。
-
使用底部的输出模板生成报告。首先列出不安全的项目。
对于引擎和框架特定的深度信息,按需加载参考文件:
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+ 重用已验证的检查并跳过扫描)→ 可选地删除该检查。 |
| 3 | CREATE INDEX(非并发) | 在整个构建过程中持有 SHARE 锁,阻塞写入。 | CREATE INDEX CONCURRENTLY —— 必须在事务外部运行;如果失败可能会留下一个 INVALID 索引(删除并重试)。 |
| 4 | DROP 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。 |
| 8 | ALTER COLUMN … TYPE | 通常会在 ACCESS EXCLUSIVE 下重写表及其索引。(例外:放宽/删除 varchar 长度限制是纯元数据操作。) | 扩展/收缩:添加新列,双写 + 回填,切换读取,删除旧列。 |
| 9 | 重命名字段/表 | DDL 是瞬间完成的,但一旦提交就会破坏正在运行的应用程序版本。 | 绝不在生产环境中原地重命名。扩展/收缩:添加新名称,双写,回填,切换读取,删除旧名称——跨越两次部署。 |
| 10 | DROP 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 安全。> <一行结论。>
始终提供用户可以直接复制并运行的安全重写方案——而不仅仅是做什么的描述。