database-migration

database-migration skill 概覽

database-migration skill 可以幫你做什麼

database-migration skill 專門用來規劃與產出資料庫 schema 與資料遷移工作，涵蓋常見的 ORM 與 SQL 工作流程，並特別重視 rollback 安全性與 zero-downtime 發布。如果你的需求不只是泛泛地「寫一個 migration」提示，而是牽涉到正式環境中的資料、需要分階段部署，或必須配合特定 migration framework（例如 Sequelize 或 TypeORM），那麼這個 database-migration skill 會比一般提示更實用。

哪些人適合使用這個 database-migration skill

最適合的使用者包括 Database Engineering 團隊、後端工程師、平台工程師，以及使用 AI 輔助開發、但需要兼顧實際部署與營運風險的開發者。如果你正在修改資料表、回填資料、安全地重新命名欄位，或在不同 ORM 模式之間轉換，這個 skill 能提供比空白提示更穩健的預設思路，而不只是產出語法上看似正確的內容。

這個 skill 最擅長解決的工作

當你的真實任務是要做出「可以真的執行」的 migration 計畫時，就該用 database-migration skill：包括 migration 檔案、分階段 rollout 步驟、rollback 路徑，以及資料轉換時要考量的細節。它的核心價值不只是產生程式碼，而是降低 migration 在執行順序、相容期設計與失敗復原上的猜測成本。

與一般 coding prompt 相比，主要差異在哪裡

和普通提示相比，這個 database-migration skill 明確偏重於：

• 具 ORM 脈絡的 migration 範例
• 清楚區分 up 與 down 的模式
• zero-downtime 思維
• 同時涵蓋 schema 變更與資料變更的流程
• 把 rollback 程序視為一等需求

因此，若是正式環境的變更需求，它會比單純的「幫我產生 SQL」更合適。

哪些屬於範圍內，哪些不是

目前這個 skill 的內容，最強的是 migration pattern 與範例結構，尤其是 Sequelize 與 TypeORM。至於 repository 專屬的自動化、驗證腳本與決策規則，相對就比較少，因為 skill 資料夾目前只公開了 SKILL.md。這代表它很適合用來引導與起草 migration 工作，但若要得到可靠輸出，你仍然需要提供自己的技術堆疊細節、限制條件與部署模式。

如何使用 database-migration skill

database-migration skill 的安裝情境

如果你是透過這個 repository 的 Skills 系統來使用，先從 repo 安裝這個 skill，然後在已經能存取你程式碼庫與 schema 脈絡的 agent session 中呼叫它。典型安裝方式如下：

npx skills add https://github.com/wshobson/agents --skill database-migration

由於這個 skill 主要是以單一 SKILL.md 提供內容，它的實際價值很大程度取決於你怎麼描述需求，以及你提供了多少 schema 脈絡。

使用前先讀這個檔案

先從這裡開始：

• plugins/framework-migration/skills/database-migration/SKILL.md

因為這個 skill 沒有看得到的輔助 rules/、resources/ 或 scripts，所以不需要花很長時間做 repo 導讀。最實用的閱讀路徑很簡單：先看 SKILL.md，接著就直接進入你自己的 schema 檔案、ORM 設定與既有 migration 歷史。

這個 skill 需要哪些輸入，效果才會好

如果你提供以下資訊，database-migration skill 的表現會明顯更好：

• 目前使用的 ORM 或 migration 工具：Sequelize、TypeORM、Prisma、原生 SQL 等
• 目前的 schema 或 model 定義
• 目標 schema 變更內容
• 是否需要資料 backfill
• 資料表大小或流量敏感度
• 可容忍的停機程度
• rollback 預期
• 目標資料庫引擎：PostgreSQL、MySQL 等
• 部署方式：一次到位、分階段、blue/green、canary

如果缺少這些細節，模型很可能會回傳一個看似合理、但對正式環境並不安全的 migration。

把模糊需求寫成更強的 database-migration prompt

較弱的 prompt：

Create a migration to rename a column.

更強的 prompt：

Use the database-migration skill. We use TypeORM with PostgreSQL.
Current table: users(id, full_name, created_at).
Goal: replace full_name with first_name and last_name.
Constraints: production table has 20M rows, cannot block writes, rollout must be zero-downtime, app and migration may be deployed separately.
Need:
1. phased migration plan
2. TypeORM migration files
3. data backfill strategy
4. rollback plan
5. application compatibility notes during transition

第二種寫法讓 skill 能判斷應該採用較安全的 expand-migrate-contract 方式，而不是冒險直接 rename。

真實 migration 任務的最佳工作流程

一個實用的 database-migration usage 流程如下：

1. 先要求 migration 策略。
2. 檢查風險、鎖表行為與 rollback 假設。
3. 再要求對應 framework 的實際 migration 檔案。
4. 如果 rollout 是分階段的，再要求 app 層的相容性調整。
5. 要求驗證查詢與 rollback 步驟。
6. 在接近正式環境資料型態的 staging 中先跑過，再決定是否採用。

這個順序很重要，因為太早產生 migration 程式碼，常常會把錯誤的 rollout 模型直接寫死。

這個 skill 最擅長的 ORM 模式

從 repository 可見的內容來看，明確提供範例的包括：

• Sequelize migrations
• TypeORM migrations

說明文字雖然也提到更廣泛的 ORM／平台 migration 使用情境，但目前看得到的範例仍以這兩個生態系最完整。如果你用的是其他技術堆疊，最好明確要求模型把相同的 migration 意圖轉成你的工具鏈，而不是預設它對你的框架也有同樣深度。

什麼情況下要明講 zero-downtime 指引

不要預設模型一定會自動以線上遷移安全性為優先。若符合以下任一情況，請直接寫明：

• 大型資料表
• 高寫入量
• app 與 DB 獨立部署
• 欄位 rename 或型別變更
• 熱路徑上的 backfill
• 正式流量中的 constraint 變更

對於 Database Engineering 團隊來說，database-migration skill 在這裡往往就是「玩具答案」和「可部署方案」之間的分水嶺。

建議向 skill 要求哪些輸出

若你希望有較高把握，請讓 database-migration skill 回傳一整包內容，而不只是單一檔案：

• migration 程式碼
• rollout 順序
• rollback 順序
• data backfill 邏輯
• 假設與風險
• 驗證清單
• migration 後的清理步驟

這樣可以避免把隱性的營運工作遺漏掉。

對直接破壞性變更的實務提醒

這個 skill 的一大用途，就是避免出現以下這種不安全的一步到位變更：

• 立刻刪除舊欄位
• 沒有相容性設計就直接原地 rename 熱門欄位
• 型別變更卻沒有轉換策略
• 在 backfill 前就先加上 non-null constraint
• 沒有規劃 lock 影響就重寫大型資料表

如果你拿到的第一版輸出包含上述任何做法，請要求它改成分階段方案。

database-migration skill 常見問題

這個 database-migration skill 只能用在 ORM migrations 嗎

不是。這個 skill 的設計是針對跨 ORM 與不同平台的資料庫 schema 與資料遷移。實務上，目前看得到的範例偏向 ORM，尤其是 Sequelize 與 TypeORM，所以最好的做法是清楚說明你的技術堆疊，並在需要時要求它轉成 SQL 或你的 framework 寫法。

database-migration skill 適合新手嗎

可以，但有限度。它的範例很具體，所以容易上手；不過它也預設你有能力判斷某個 migration 在營運上是否安全。新手可以用它來起草 migration 檔案與 rollout 計畫，但不應該把第一版答案直接視為可上正式環境的最終結果，仍然需要審查。

什麼情況下不該使用 database-migration

如果你的任務純粹是概念討論，並不是要實際執行 schema／資料變更，那就不太需要這個 skill。另一種不適合的情況，是你期待只靠這個 repository 就得到完整、環境專屬的驗證能力；因為這個 skill 目前公開的資料夾中，並沒有額外 scripts、rules 或 test harness 可直接依賴。

它和直接叫 AI 寫 SQL 相比，好在哪裡

database-migration guide 的真正價值，在於它把問題框定在完整的 migration 生命週期，而不只是語法。單純的 SQL prompt 常會漏掉 rollback、相容期、分階段 backfill，以及 ORM migration 慣例。當部署安全性和程式碼正確性同樣重要時，這個 skill 會更有用。

它支援 zero-downtime deployments 嗎

支援，這正是它明確的使用場景之一。不過你還是需要定義在你的環境中，zero-downtime 具體代表什麼。光是這個詞太籠統，模型還需要知道你的部署順序、讀寫流量型態，以及相容性限制。

如何提升 database-migration skill 的效果

同時提供 schema diff 與營運限制

想最快提升 database-migration 輸出品質，最有效的方法就是把 schema 變更與執行環境限制一起提供。例如：

Current: orders.status VARCHAR nullable
Target: orders.status ENUM not null
DB: PostgreSQL
Rows: 80M
Traffic: constant writes
Requirement: no downtime, rollback available, deploy app separately

這樣會把模型導向分階段 migration 設計，而不是只吐出一條過度簡化的 alter statement。

安全性重要時，直接要求 expand-migrate-contract

如果第一版看起來太具破壞性，就明確要求 expand-migrate-contract 計畫。這通常會改善以下情境的結果：

• rename
• 型別轉換
• 引入 non-null
• 拆表
• denormalization 或 normalization 調整

這是讓 skill 產出更好 database-migration usage 的最可靠方法之一。

在第一版回覆就要求 validation 與 rollback

常見失敗模式之一，是拿到一個看似正確的 up migration，但 down 很弱，甚至不切實際。要改善這點，可以一開始就要求：

• rollback 條件
• 資料遺失警告
• 驗證查詢
• 每個階段完成後的成功判準

這會迫使模型在早期就思考可逆性。

提供你 repo 既有的 migration 風格

如果你的專案本來就有 migration 慣例，貼上一到兩個具代表性的檔案，並要求 skill 對齊。這會明顯改善命名方式、transaction 處理、timestamp 風格與 framework 慣用寫法。對 Sequelize 和 TypeORM 特別有幫助，因為很多團隊都會在 framework 預設之外建立自己的在地規範。

迭代時不要只看程式碼正確性，也要追問 lock 風險

拿到第一版後，可以接著追問這類問題：

• 哪些步驟可能會 lock 住資料表？
• 哪些步驟可以在持續寫入時執行？
• 哪些內容應該拆成不同 deploy？
• 哪一部分在 backfill 後就不可逆？
• rollout 期間應該監看哪些指標？

很多時候，database-migration skill 真正對 Database Engineering 工作產生價值，就是從這一層開始，而不只是幫你生 boilerplate。

留意這些常見失敗模式

如果產生的 migration 有以下情況，請提高警覺：

• 預設資料表很小
• 沒有 rollback
• 太早刪除舊欄位
• 把 schema 變更和大規模 backfill 合併成單一步驟
• 忽略過渡期間的 app 相容性
• 使用與你版本不符的 framework 語法

這些都很常見，通常代表你需要再 refine prompt，不代表這個 skill 不能用。

第一版之後，最佳的改進方式

把第一版答案當成 migration 提案，而不是最終成品。接著再請 skill 根據以下資訊修正：

• 你的實際資料表大小
• index 現況
• 預期 deploy 順序
• canary 或 staging 的發現
• 審查後確認失準的假設

這種回饋迴圈，是把 database-migration install 與使用流程真正轉化成正式環境等級價值的最實際方法。