安全遷移 (Safe Migrations) 是做什麼的?
在悄悄鎖定資料表或觸發磁碟重寫的 schema 變更抵達生產環境前,就將它們轉換為安全、零停機的遷移。
一個看似無害的指令(SET NOT NULL、CREATE INDEX、ADD FOREIGN KEY、或帶有 DEFAULT 的資料行)可能會取得 ACCESS EXCLUSIVE 鎖定,或強制執行完整資料表重寫。在龐大且繁忙的資料表上,這意味著所有的讀取和寫入都會排隊在遷移之後——即是一次停機。此技能會審查遷移,清楚說明什麼會被鎖定以及為什麼,並產出安全的改寫版本。
何時使用這個技能
- 你在撰寫新的遷移,並希望在提交前進行檢查。
- 你在審查 Pull Request / diff 中的遷移。
- 你即將執行一個針對已有資料行的資料表的遷移。
- 有人問:「這個遷移安全嗎?」、「這會鎖定資料表嗎?」或「我如何以零停機的方式做到這件事?」。
如果目標資料表是空的或很小(在同一個遷移中建立的新資料表、只有少量資料行的設定檔資料表),那麼大部分風險都不適用——請直接說明並避免過度設計。
工作流程
-
建立背景資訊。 確認引擎(PostgreSQL 或 MySQL / MariaDB,如果可以,也請確認主要版本)與框架。版本很重要:某些操作在 Postgres 11 / 12 以上是安全的,但在之前的版本則不是。如果版本未知,請標記那些安全性會依賴版本的操作。
-
定位操作。 讀取每一個遷移檔案,並列出其中所有執行的 schema 或資料操作。一個遷移經常包含多個操作。
-
根據以下風險目錄對每個操作進行分類。 指定嚴重性:
- 🔴 不安全 — 將會取得阻塞鎖定、重寫資料表或破壞正在執行的應用程式版本。必須改寫。
- 🟡 需注意 — 僅在特定條件下安全(小資料表、特定引擎版本、低流量、正確的設定)。請指出該條件。
- 🟢 安全 — 僅中繼資料操作或其他非阻塞操作。無需變更。
-
改寫不安全的操作。 對於每個 🔴/🟡,提供:
- 具體的風險(哪種鎖定、它阻塞了什麼、粗略的影響),
- 一個安全改寫,以可執行的步驟呈現(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 交易、以及拆分狀態與 schema。
請閱讀與你面前遷移相關的參考檔案,而不是猜測版本特定的行為。
風險目錄(高頻觸發項目)
以 PostgreSQL 為中心;MySQL 的差異請見 reference/mysql.md。「重寫」= 整個資料表在磁碟上被複製;「掃描」= 完整讀取資料表;兩者都在一個阻塞並發流量的鎖定下進行。
| # | 操作 | 為什麼危險 | 安全做法 |
|---|---|---|---|
| 1 | 新增帶有 DEFAULT 的資料行 | 變動型預設值(例如 gen_random_uuid()、random())會在 ACCESS EXCLUSIVE 鎖定下重寫資料表。任何預設值都會在 Postgres < 11 上重寫。 | 先新增一個可為 NULL 且無預設值的資料行 → ALTER … SET DEFAULT(僅影響新資料行)→ 分批回填現有資料行 → 新增 NOT NULL(第 2 點)。 |
| 2 | 在現有資料行上使用 SET NOT NULL | 在 ACCESS EXCLUSIVE 鎖定下執行完整資料表掃描,以驗證沒有 NULL 值——會阻塞讀取和寫入。 | 新增 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 | RENAME 資料行 / 資料表 | DDL 是瞬時的,但它在提交的瞬間就會破壞正在執行的應用程式版本。 | 永遠不要在運行的應用程式上就地重新命名。擴展 / 收縮:新增新名稱,雙重寫入,回填,切換讀取,刪除舊名稱——跨越兩個部署。 |
| 10 | DROP COLUMN | 仍在引用它的應用程式程式碼(包括 SELECT *)會中斷;資料已消失(難以回滾)。 | 僅限收縮階段:先部署已停止使用該資料行的應用程式程式碼,然後在後續的遷移中刪除。 |
| 11 | 在一個大的 UPDATE 中回填 | 長時間運行的交易 → 鎖定競爭、資料表膨脹、複寫延遲。 | 按主鍵範圍分批處理,批次之間提交;保持每個批次簡短。在 schema 遷移外部執行。 |
| 12 | 沒有 lock_timeout / statement_timeout | 即使是瞬時的 DDL 也需要一個簡短的 ACCESS EXCLUSIVE 鎖定。如果它在一個長時間查詢後面排隊,它會阻塞在其之後到達的每一個查詢——導致串聯停機。 | 在 DDL 之前設定一個較低的 lock_timeout(和 statement_timeout),以便遷移快速失敗,而不是導致網站停機。 |
指導原則
- 擴展 / 收縮(並行變更)。 任何不相容於舊版的變更都必須拆分,以便資料庫在部署期間同時與舊版和新版應用程式相容。擴展(新增,向後相容)→ 遷移資料 / 雙重寫入 → 收縮(移除)——通常跨越兩個或更多部署。這是重新命名、型別變更、拆分和合併的核心。
- 每個遷移一個邏輯變更。 更容易審查、推理和回滾。切勿在同一個交易中混合 schema 變更和大量資料回填。
- N-1 相容性。 在部署期間,兩個版本的應用程式會同時運行。Schema 必須能夠同時服務兩者。
- 將 Schema 與資料分開。 結構性 DDL 和資料行回填屬於不同的步驟(通常在不同的部署中)。
- 建議要適度。 空白、很小或全新的資料表不需要這些。不要將只有兩行的變更變成五個步驟的舞蹈。
輸出範本
## 遷移安全性審查
**引擎:** <例如 PostgreSQL 14> · **框架:** <例如 Rails> · **審查的檔案:** <數量>
### 🔴 <檔案> — 不安全
**操作:** <做了什麼>
**風險:** <哪種鎖定 / 重寫,它阻塞了什麼>
**可能影響:** <例如「對 `users` 進行完整掃描期間的全域鎖定;在一個 4000 萬筆資料行的資料表上,可能導致數秒到數分鐘的流量阻塞」>
**安全改寫:**
<可執行的步驟 — SQL 和 / 或框架程式碼>
**部署順序:** <僅當應用程式程式碼必須同步變更時>
### 🟡 <檔案> — 需注意
**操作 / 風險 / 條件 / 建議**
### 🟢 <檔案> — 安全
<一行:為什麼安全,無需操作>
---
**摘要:** <n 個不安全,n 個需注意,n 個安全。> <一行總結。>
始終將安全改寫呈現為使用者可以直接複製並執行的內容——而不僅僅是描述該做什麼。