Community寫作與編輯github.com

安全遷移 (Safe Migrations)

在資料庫遷移導致資料表鎖定之前,及早發現並修正問題。此 Claude Agent 技能可審查遷移腳本中的停機風險,並將其改寫為安全、零停機的步驟。支援 PostgreSQL 與 MySQL,適用於任何框架。

安全遷移 (Safe Migrations) 是什麼?

這項技能旨在防止資料庫遷移作業對生產環境造成停機。它能夠分析遷移腳本中的每一個操作,判斷它是否會導致資料表被獨佔鎖定或觸發完整資料表重寫——這兩種情況在高流量的資料表上都可能造成服務中斷。根據風險程度將操作分為不安全、需注意和安全三類,並針對不安全的操作提供具體的鎖定風險說明與安全改寫建議。改寫建議包含可執行的 SQL 指令以及框架慣用寫法,並會規劃應用程式的部署順序以確保向後相容。此技能支援 PostgreSQL 和 MySQL / MariaDB,並提供引擎特定的參考文件(如 postgres.md 和 mysql.md)以及跨引擎的最佳實踐模式。

相容平台✓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 的新對話。

說明文件

安全遷移 (Safe Migrations) 是做什麼的?

在悄悄鎖定資料表或觸發磁碟重寫的 schema 變更抵達生產環境前,就將它們轉換為安全、零停機的遷移。

一個看似無害的指令(SET NOT NULL、CREATE INDEX、ADD FOREIGN KEY、或帶有 DEFAULT 的資料行)可能會取得 ACCESS EXCLUSIVE 鎖定,或強制執行完整資料表重寫。在龐大且繁忙的資料表上,這意味著所有的讀取和寫入都會排隊在遷移之後——即是一次停機。此技能會審查遷移,清楚說明什麼會被鎖定以及為什麼,並產出安全的改寫版本。

何時使用這個技能

  • 你在撰寫新的遷移,並希望在提交前進行檢查。
  • 你在審查 Pull Request / diff 中的遷移。
  • 你即將執行一個針對已有資料行的資料表的遷移。
  • 有人問:「這個遷移安全嗎?」、「這會鎖定資料表嗎?」或「我如何以零停機的方式做到這件事?」。

如果目標資料表是空的或很小(在同一個遷移中建立的新資料表、只有少量資料行的設定檔資料表),那麼大部分風險都不適用——請直接說明並避免過度設計。

工作流程

  1. 建立背景資訊。 確認引擎(PostgreSQL 或 MySQL / MariaDB,如果可以,也請確認主要版本)與框架。版本很重要:某些操作在 Postgres 11 / 12 以上是安全的,但在之前的版本則不是。如果版本未知,請標記那些安全性會依賴版本的操作。

  2. 定位操作。 讀取每一個遷移檔案,並列出其中所有執行的 schema 或資料操作。一個遷移經常包含多個操作。

  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 交易、以及拆分狀態與 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+ 會重複使用已驗證的檢查並跳過掃描)→ 可選擇性地刪除該檢查。
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 長度限制僅是中繼資料操作。)擴展 / 收縮:新增一個資料行,雙重寫入 + 回填,切換讀取,刪除舊資料行。
9RENAME 資料行 / 資料表DDL 是瞬時的,但它在提交的瞬間就會破壞正在執行的應用程式版本。永遠不要在運行的應用程式上就地重新命名。擴展 / 收縮:新增新名稱,雙重寫入,回填,切換讀取,刪除舊名稱——跨越兩個部署。
10DROP 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 個安全。> <一行總結。>

始終將安全改寫呈現為使用者可以直接複製並執行的內容——而不僅僅是描述該做什麼。

相關技能