Hasura Migration 的 Git 版本控制與 CI/CD 自動部署 – 新手完全指南

Published August 6, 2025 by 徐培鈞
Web API

想像一下，你和同事一起開發一個網站，你們需要經常修改資料庫（比如新增資料表、改欄位名稱等）。如果沒有好的管理方式，很容易出現這些問題：

  • 🤔 同事修改了資料庫，但你不知道改了什麼
  • 😱 不小心刪錯資料表，想要復原卻不知道怎麼辦
  • 🔥 正式環境和開發環境的資料庫結構不一樣，導致程式出錯

這篇文章要教你如何用 Hasura 的 Migration 功能，配合 Git 和自動部署，讓這些問題通通消失！

適合誰看這篇文章？

  • 剛開始使用 Hasura 的開發者
  • 想要建立團隊開發流程的人
  • 對資料庫版本控制有興趣的新手

什麼是 Hasura Migration？

Migration 就像是資料庫的「歷史紀錄」

把 Migration 想像成你修改資料庫的「日記本」：

  • 📝 今天做了什麼：新增了一個使用者資料表
  • 🔄 怎麼做的：執行了 CREATE TABLE users... 這個 SQL 指令
  • ↩️ 怎麼復原：如果要取消，就執行 DROP TABLE users

每當你在 Hasura Console 上做任何修改，Hasura 就會自動幫你寫一筆「日記」，記錄你做了什麼。

為什麼需要 Migration？

沒有 Migration 的痛苦：

開發者 A：「我剛剛新增了 email 欄位」
開發者 B：「咦？我這邊沒有 email 欄位，程式壞了！」
開發者 A：「你要手動加一下...」

有了 Migration 的美好：

開發者 A：「我剛剛新增了 email 欄位，執行 hasura migrate apply 就好了」
開發者 B：「好的！」（一行指令搞定）

建立你的第一個 Hasura Migration 專案

專案初始化

步驟 1：安裝 Hasura CLI

# Windows (使用 chocolatey)
choco install hasura-cli

# Mac (使用 homebrew)
brew install hasura-cli

# 或是直接下載執行檔

步驟 2：建立專案資料夾

mkdir my-hasura-project
cd my-hasura-project
hasura init

步驟 3：連接到你的資料庫

hasura console

認識專案結構（不用背，看懂就好）

執行完上面的指令後，你會看到這樣的資料夾：

my-hasura-project/
├── migrations/          # 📁 資料庫變更紀錄放這裡
├── metadata/           # 📁 Hasura 設定檔放這裡
├── seeds/              # 📁 初始資料放這裡（選用）
└── config.yaml         # ⚙️ 設定檔

重點記住：

  • migrations/ = 資料庫結構的變更紀錄
  • metadata/ = Hasura 的各種設定（權限、關聯等）

為什麼 Migration 還需要 Git？（解答新手疑惑）

Migration 和 Git 的差別在哪？

很多人會問：「Migration 不就是資料庫的歷史紀錄嗎？為什麼還要 Git？」

讓我用一個生活化的例子來解釋：

Migration = 你個人的日記本

  • 📝 記錄你今天對資料庫做了什麼
  • 💾 檔案存在你的電腦裡
  • 🏠 只有你知道發生了什麼事

Git = 全家人共用的家庭記事本

  • 📚 把所有人的日記本內容統一管理
  • ☁️ 存在雲端，大家都能看到
  • 👥 協調不同人的修改，避免衝突

實際問題：沒有 Git 會發生什麼事？

情境 1：檔案遺失災難

開發者 A：「我的 Migration 檔案不見了！」
開發者 B：「我也不知道你之前改了什麼...」
結果：💥 整個專案要重新來過

情境 2：團隊同步混亂

開發者 A 的電腦：
├── migrations/
│   ├── 001_create_users.sql
│   └── 002_add_email_field.sql

開發者 B 的電腦：
├── migrations/
│   ├── 001_create_users.sql
│   ├── 002_add_posts_table.sql  ← 不一樣！
│   └── 003_add_comments.sql

誰的版本才是對的？ 🤷‍♂️

有了 Git 之後的美好世界

統一的版本：

GitHub 上的正確版本：
├── migrations/
│   ├── 001_create_users.sql
│   ├── 002_add_email_field.sql
│   ├── 003_add_posts_table.sql
│   └── 004_add_comments.sql

所有人都從這裡同步 ✅

清楚的協作流程：

  1. 📥 每天開工前：git pull 取得最新的 Migration 檔案
  2. 🛠️ 開發時：在 Hasura Console 做修改，自動產生新的 Migration
  3. 📤 完成後：git push 分享給團隊
  4. 🔄 其他人：git pull + hasura migrate apply 同步變更

Migration 與 Git 的分工

Migration 負責✅ 記錄資料庫架構變更
Git 負責✅ 記錄 Migration 檔案的版本
Migration 負責❌ 只存在本機
Git 負責✅ 雲端同步，團隊共享
Migration 負責❌ 無法處理多人修改
Git 負責✅ 自動合併或提示衝突
Migration 負責✅ 資料庫變更歷史
Git 負責✅ 檔案修改歷史 + 誰改的
Migration 負責❌ 檔案可能遺失
Git 負責✅ 多重備份，永不遺失

Git 版本控制設定

設定 Git（5 分鐘搞定）

步驟 1：初始化 Git

cd my-hasura-project
git init

步驟 2：建立 .gitignore 檔案

# .gitignore
.env
*.log
node_modules/
.DS_Store

步驟 3：第一次提交

git add .
git commit -m "初始化 Hasura 專案"

團隊開發流程（重要！）

標準工作流程：

開始新功能前

git pull origin main  # 拉取最新版本
hasura migrate apply  # 套用最新的資料庫變更
hasura metadata apply # 套用最新的 Hasura 設定

開發過程中

# 在 Hasura Console 做修改
hasura console

# 修改完成後
git add migrations/ metadata/
git commit -m "新增使用者登入功能"
git push origin feature/user-login

合併到主分支

# 透過 Pull Request 合併
# 其他人就能透過 git pull 取得你的變更

CI/CD 自動部署設定

什麼是 CI/CD？（簡單說明）

CI/CD 就像是「自動化助手」：

  • 📤 你把程式碼推到 Git
  • 🤖 系統自動測試、自動部署
  • ✅ 省時省力，減少人為錯誤

使用 GitHub Actions（最受歡迎的選擇）

步驟 1：建立 GitHub Actions 設定檔

在專案根目錄建立 .github/workflows/deploy.yml：

name: 部署 Hasura

on:
  push:
    branches: [ main ]  # 推到 main 分支時觸發

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - name: 下載程式碼
      uses: actions/checkout@v3

    - name: 安裝 Hasura CLI
      run: |
        curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | bash

    - name: 套用 Migration
      run: |
        hasura migrate apply --endpoint ${{ secrets.HASURA_ENDPOINT }} --admin-secret ${{ secrets.HASURA_ADMIN_SECRET }}
        hasura metadata apply --endpoint ${{ secrets.HASURA_ENDPOINT }} --admin-secret ${{ secrets.HASURA_ADMIN_SECRET }}

步驟 2：設定密鑰（重要安全設定）

在 GitHub 專案設定中新增這些秘密變數：

  • HASURA_ENDPOINT：你的 Hasura 伺服器網址
  • HASURA_ADMIN_SECRET：管理員密碼

部署流程說明

自動化流程：

  1. 🔄 開發者推程式碼到 GitHub
  2. 🚀 GitHub Actions 自動啟動
  3. 📥 下載最新程式碼
  4. 🛠️ 安裝 Hasura CLI
  5. 📊 套用資料庫變更
  6. ⚙️ 套用 Hasura 設定
  7. ✅ 部署完成！

實戰演練：完整開發流程

情境：新增「文章」功能

需求：

  • 新增文章資料表
  • 設定與使用者的關聯
  • 設定權限

步驟 1：開始開發

git checkout -b feature/add-posts
hasura console

步驟 2：在 Console 中操作

  1. 建立 posts 資料表
  2. 新增欄位：id, title, content, user_id, created_at
  3. 設定與 users 資料表的關聯
  4. 設定權限（使用者只能編輯自己的文章）

步驟 3：提交變更

git add migrations/ metadata/
git commit -m "新增文章功能與權限設定"
git push origin feature/add-posts

步驟 4：合併與部署

  1. 建立 Pull Request
  2. 團隊 Review
  3. 合併到 main 分支
  4. 🤖 自動部署到正式環境

如果出錯怎麼辦？

常見問題與解決方法：

問題 1：Migration 套用失敗

# 檢查錯誤訊息
hasura migrate status

# 如果需要回滾
hasura migrate apply --version [previous_version] --type down

問題 2：多人開發衝突

# 先拉取最新版本
git pull origin main

# 解決衝突後重新套用
hasura migrate apply
hasura metadata reload

問題 3：正式環境與開發環境不同步

# 強制同步（小心使用）
hasura migrate apply --skip-update-check
hasura metadata apply

最佳實踐與注意事項

開發習慣建議

✅ 好習慣：

  • 每個功能建立獨立分支
  • Migration 訊息要清楚描述做了什麼
  • 定期同步主分支的變更
  • 測試環境先驗證再推到正式環境

❌ 壞習慣：

  • 直接在正式環境手動修改資料庫
  • 不寫 Migration 訊息或寫得很模糊
  • 多天不同步主分支變更
  • 跳過測試直接部署

安全性考量

重要提醒：

  • 🔐 絕對不要把 HASURA_ADMIN_SECRET 寫在程式碼裡
  • 🚫 不要把 .env 檔案提交到 Git
  • 🛡️ 正式環境的資料庫要定期備份
  • 👥 團隊成員權限要適當分配

效能優化建議

Migration 執行優化：

  • 大量資料變更時，考慮分批執行
  • 建立索引的 Migration 要在離峰時間執行
  • 定期清理過舊的 Migration 檔案

結語

透過這套完整的 Hasura Migration + Git + CI/CD 流程，你的團隊可以：

  • ✅ 安全地管理資料庫架構變更
  • ✅ 避免環境不一致的問題
  • ✅ 提高開發效率
  • ✅ 降低部署風險
  • ✅ 建立可靠的團隊協作流程

記住這些重點：

  1. 每次修改都要透過 Migration
  2. 定期同步團隊變更
  3. 善用自動化部署
  4. 遇到問題不要慌，大部分都有解決方案

下一步該做什麼？

  • 在測試專案中練習這套流程
  • 與團隊討論並建立開發規範
  • 逐步導入到正式專案中

祝你在 Hasura 的開發路上順利！如果遇到問題，記得查看官方文件或在社群中尋求協助。