Hasura Migration 的三種類型一次搞懂：初學者也能快速判斷
更新日期： 2025 年 8 月 6 日
剛開始使用 Hasura 的時候，你一定碰過這種情況：
- 「加個新欄位需要做 migration 嗎？」
- 「只是調整某個角色的權限，該不該一起版本控制？」
- 「如果只是塞幾筆假資料，還要同步到其他環境嗎？」
這些問題看似簡單，但如果判斷錯誤，可能會導致團隊環境不同步，或者版本庫充滿沒必要的 migration 檔案。
別擔心，這篇文章會用圖解、生活化比喻帶你一次搞懂 Hasura Migration 的三種類型，並教你如何用一句話就快速判斷「要不要做 Migration」。
Hasura Migration 三種類型總覽：一次搞懂三種層級的差異
在使用 Hasura 進行專案開發時，我們常常需要在不同環境（例如本地、測試、正式環境）之間同步變更。
這些變更在 Hasura 的世界裡，被統稱為 Migration（遷移），主要分成三種類型，每種類型的「影響層級」不同，所需的同步與版本控制方式也不同。
為什麼要分三種類型？
在初學者眼中，所有變更看起來都差不多：
「不就是資料改一改，為什麼有的要做 Migration，有的不用？」
但實際上，不同類型的變更對專案的影響差異非常大，如果不加以分類並正確處理，會讓整個團隊的開發流程變得混亂、風險倍增。
🧨 第一種錯誤：什麼都不做 Migration
有些人會想：「啊我只是加個欄位、改一下表格名稱，大家自己手動改一下就好了吧。」
結果到了測試或正式環境時才發現：
- 查詢結果突然錯誤：因為欄位不見了。
- GraphQL schema 解析錯誤：因為 Hasura 找不到你新增的欄位。
- 新同事剛拉下 repo 卻怎麼樣都跑不起來。
👉 原因其實很簡單：你改了「資料庫結構」，但沒有被追蹤與同步。
這種情況就會導致「我這邊可以跑、你那邊卻壞掉」的災難場景。
📦 第二種錯誤：什麼都做 Migration
另一種極端是：
「只要資料有變動我就做 Migration！要嚴謹就全部都記錄起來！」
表面上看起來很負責，但這麼做反而會讓版本庫變得臃腫不堪。你可能會看到：
- 每天都有 10 個 migration commit，內容都是塞測試資料或改一兩筆紀錄。
- 團隊花了大量時間 review 無關緊要的
up.sql。 - 上線部署時還要多花時間套用一堆根本不影響系統的資料操作。
👉 結果是什麼？版本控制反而變得沒效率，團隊也漸漸不信任 Migration 系統。
所以 Hasura 幫你分類好三種類型
為了解決以上問題，Hasura 把 Migration 分成三個明確的層級：
| 層級 | 對應的變化 | 是否需要版本控制 | 原因 |
|---|---|---|---|
| Database Migration | 資料庫結構 | ✅ 一定要 | 否則各環境結構不一致，導致查詢錯誤或系統當機 |
| Metadata Migration | Hasura 設定（權限、關聯） | ✅ 建議要 | 避免資料拿不到、操作不一致 |
| Data-only | 純資料內容 | ❌ 不需要 | 不影響系統結構，不需同步也不會壞掉 |
這樣的設計讓你可以根據實際需求，判斷哪些要嚴格控管、哪些可以靈活處理。不僅減少不必要的同步，也讓團隊溝通變得更清楚。
🎯 總結一句話：
「不是每一種變更都需要被記錄在版本控制裡。Hasura 幫你分好了三種類型，就是要讓你做對事、用對工具。」
詳細解讀三種類型
Hasura Migration 的三種類型分別對應到不同層級的變更。
你可以把它想像成一棟大樓的三個層面：
最底層是大樓結構（Database）、中間層是管理規則（Metadata）、最外層是住戶的日常擺設（Data-only）。
下面我們逐一拆解。
Database Migration：最核心、最不能忽略
它是什麼？
Database Migration 負責追蹤任何影響資料庫結構的變化，常見的動作包括：
- 新增或刪除資料表（例如新加一張
orders訂單表） - 新增欄位（例如在
users表新增phone_number欄位） - 修改欄位型別（例如將
price從integer改成numeric） - 建立索引（例如加快查詢速度的
CREATE INDEX）
這類變更就像在改建房子的地基與梁柱，一旦不同步，整棟大樓（應用程式）就可能「結構崩壞」。
為什麼一定要版本控制？
想像以下場景：
- 你在本地加了一個新欄位
phone_number，並且修改了前端程式去顯示這個欄位。 - 但正式環境的資料庫沒有這個欄位，結果當前端查詢 API 時，直接噴出 「column does not exist」 的錯誤。
這就是典型的「環境結構不同步」問題。
為了避免這種災難，Database Migration 一定要用版本控制，而且通常會透過 up.sql（定義升級動作）與 down.sql（定義回滾動作）進行嚴格追蹤。
一個完整的 Database Migration 可以保證：
- 新同事拉下 repo 後，一鍵就能建立相同的資料庫結構。
- 部署到正式環境時，能穩定套用並回滾變更。
Metadata Migration：Hasura 特有的「設定變更」
它是什麼？
Hasura 不只是單純的資料庫代理層，它還會幫你管理一層「與應用程式邏輯相關的設定」。
常見的 Metadata 變更包含：
- 權限設定（Permission）
- 例如：限制
user角色只能讀取自己的訂單資料。
- Relationship 建立（資料表關聯）
- 例如：在
orders表與users表之間建立關聯，讓前端可以直接用 GraphQL 一次查到「訂單 + 對應的使用者」。
- Event Trigger
- 例如：當有人新增訂單時，自動觸發 webhook 通知後端發送 Email。
這些變化就像是在大樓裡設定房間的門禁與水電管路，本質上不改變建築結構，但如果錯了，住戶（前端應用程式）可能就「進不去房間」或「拿不到水電」。
為什麼「建議」要版本控制？
理論上，Metadata 的變更不像 Database 那麼致命——你少一個權限設定，資料庫依然能運作；但是：
- 若正式環境少了權限設定 → 某些角色可能誤讀到不該讀的敏感資料，或者乾脆查不到任何資料。
- 若忘了建立 Relationship → GraphQL 查詢會失敗，前端畫面也可能一片空白。
因此，大部分團隊都會透過 Metadata Migration 確保多環境一致。
常見的做法是使用 Hasura CLI 的：
hasura metadata export（匯出當前設定）hasura metadata apply（套用到其他環境）
這樣能確保：
- 測試環境、正式環境、開發環境用的是一樣的設定。
- 新成員在本地快速還原設定，不用手動點選 Hasura Console。
Data-only：只是操作資料本身
它是什麼？
這一類完全是資料內容層面的操作，例如：
- 批次塞入假資料（測試階段新增 100 筆會員資料）
- 更新產品價格
- 刪除過期的臨時資料
這些動作就像是在房子裡擺放或搬走家具，完全不會影響建築結構或房間用途。
為什麼不用版本控制？
因為這些資料操作通常是一次性的業務需求，而且不同環境的資料本來就不需要完全一致。
例如：
- 測試環境可以塞假訂單資料模擬下單流程，但正式環境不需要這些假資料。
- 即使價格在測試環境不同，也不影響程式邏輯的正常執行。
若你硬要將這些操作放進 Migration，不但會增加大量無意義的 up.sql，還可能讓正式環境在套用時塞入一堆不必要的測試資料，反而增加風險。
一句話總結三種類型
- Database Migration = 改建房子結構，必須嚴格追蹤
- Metadata Migration = 設定房間用途或管路，強烈建議同步
- Data-only = 擺放家具，靈活操作、不必版本控制
快速判斷流程：我到底要不要做 Migration？
初學者在剛接觸 Hasura 時，最常見的問題就是：
「這次修改到底要不要做 Migration？」
有些人為了安全起見，什麼都做 Migration；
有些人則覺得麻煩，乾脆完全不做。
結果兩種做法都會讓專案陷入混亂——不是版本庫臃腫，就是環境不同步。
為了幫助你快速做出判斷，以下提供一個三步驟的思考流程，只要幾秒鐘就能決定。
第一步：你現在做的事，改動的是「結構」還是「資料」？
先問自己一個問題：
「我這次動到的是資料庫的『骨架』嗎？」
- 是 → Database Migration
例如：新增欄位、刪除表、修改型別，這些都會直接影響資料庫結構，必須做 Migration，否則其他環境會出現嚴重錯誤。 - 不是 → 進入第二步
第二步：你有改 Hasura 的設定嗎？
如果你沒有動資料庫結構，接下來要問的是：
「這次有動到 Hasura 的權限、關聯、觸發器等設定嗎？」
- 是 → Metadata Migration
例如：- 為新角色加讀取權限
- 建立兩個表的 Relationship
- 新增 Event Trigger 雖然這些不會破壞資料庫本身，但在跨環境時非常重要。
建議一定要透過 Metadata Migration 確保同步，否則正式環境可能出現「前端拿不到資料」的問題。 - 不是 → 進入第三步
第三步：只是單純操作資料內容嗎？
最後一步，判斷你是否只是做了一些一次性或業務性的資料操作。
- 是 → Data-only，不需要 Migration
例如：- 塞入 100 筆假會員資料
- 更新幾個產品的價格
- 刪除過期的測試資料 這類操作本來就不需要在不同環境保持一致，做 Migration 反而會增加不必要的負擔。
判斷流程圖（圖像化思考）
如果你喜歡用白板思考的風格，可以記住下面這個流程圖：
我現在做的事是什麼？
│
├─► 改動資料庫結構？ → ✅ Database Migration（一定要）
│
├─► 沒改結構，但改 Hasura 設定？ → ✅ Metadata Migration（建議要）
│
└─► 只是塞資料（INSERT / UPDATE / DELETE）？ → ❌ 不需要 Migration小提醒：
✅ Metadata Migration 雖然不是「必須」，但建議要做，特別是權限、Relationship、Event Trigger 這些設定，在多環境部署時非常重要，少同步一次可能就讓前端整個壞掉。
實務案例快速判斷
- 我在
orders表加了一個status欄位 → Database Migration - 我幫
user角色加了讀取orders的權限 → Metadata Migration - 我在測試環境塞入 50 筆假訂單 → Data-only，不需要 Migration
結語：一句話收斂 & 下一步
一句話收斂
👉 「改結構、改設定 → 要 Migration；純資料 → 不需要。」
只要掌握這個核心原則，你就不會再為「要不要做 Migration」感到困惑。
下一步：動手實作
理解判斷邏輯後，接下來就是實作了。
下一篇文章會帶你操作 Hasura Database Migration，從產生 up.sql 到如何回滾，一次看懂完整流程。