本地 Hasura vs 雲端 Console：為什麼會有兩種版本？一篇講清楚

如果你剛接觸 Hasura，可能會有這些疑問：

• 「Hasura 是資料庫嗎？還是某種雲端服務？」
• 「為什麼它有本地版，也有雲端 Console？我該用哪一個？」

這些疑問很正常，因為 Hasura 和我們熟悉的「資料庫」或「後端框架」都不一樣。

它本質上是一個 在資料庫上快速生成 API 的引擎，而且同時提供 「自己架設」的本地版本 和 「官方托管」的雲端版本，以滿足不同使用需求。

這篇文章會幫你從 Hasura 的定位與歷史背景 說起，讓你知道 為什麼 Hasura 會有這兩種版本、它們的設計理念是什麼，最後還會用 一張比較表，幫助你快速判斷 自己該用哪一個版本。

Hasura 是什麼？它是資料庫嗎？

為什麼大家會以為 Hasura 是資料庫？

很多初學者第一次接觸 Hasura 時，都會產生一個強烈的錯覺：

「這不就是一個資料庫後台嗎？我可以直接新增資料表、修改欄位，甚至直接插入和刪除資料，這不就是一個雲端資料庫嗎？」

這個錯覺非常合理，因為 Hasura Console（它的管理儀錶板）看起來幾乎和傳統的資料庫管理工具長得一模一樣。

為什麼會有這種錯覺？

• 介面上像資料庫管理工具
• 你能在左邊看到所有的 Table 名稱、欄位、Relationship，跟我們熟悉的 phpMyAdmin、pgAdmin 幾乎沒差別。
• 功能上也像資料庫
• 你能「建表、刪表、改欄位」→ 和傳統 DBA 的工作一模一樣
• 你能「直接插入、更新、刪除資料」→ 看起來就是在資料庫內編輯資料
• 你能「直接查詢資料」→ Console 的 Data 頁籤甚至就像一個 SQL Query 視窗

很多初學者看到這些功能後，自然就會把 Hasura 和 Firebase、Supabase 這種「雲端資料庫服務」畫上等號。

Hasura 的真正定位：它不是資料庫

但事實上，Hasura 並不是一個資料庫，也不取代你現有的資料庫。

Hasura 本質上是什麼？

Hasura 的本質是一個 「API 引擎」，它的核心價值是：

1. 讀取你現有的資料庫結構 → 分析出 Table、欄位、關聯關係
2. 自動生成 API → 讓你用 GraphQL / REST 的方式直接存取這些資料

✅ 一句話理解：Hasura 是一個「API 快速生成器」，而不是一個新的資料庫。

那 Hasura Console 為什麼能像資料庫一樣操作？

Console 做的只是「代替你發 SQL 指令」

你在 Hasura Console 上看到的所有操作，本質上只是 Hasura 幫你向底層資料庫發送 SQL 指令而已。

舉個具體例子：

所以當你在 Console 上「新增一筆資料」時，資料實際是存進你自己連接的 PostgreSQL / MySQL 資料庫裡，而不是 Hasura 自己維護的某個獨立儲存系統。

✅ Hasura 自己沒有資料庫，它只是你和資料庫之間的「代理人」。

Hasura 的運作邏輯：它在系統中的角色

你可以把 Hasura 想像成一個「聰明的服務生」：

• 你給它一張菜單（資料庫結構） → 它自動看懂每道菜是什麼（哪些 Table、哪些欄位）
• 你告訴它想吃什麼（GraphQL / REST 請求） → 它幫你到廚房（資料庫）拿正確的菜（資料）
• 它本身不煮菜（不存資料） → 它只負責「幫你拿、幫你送」

在技術層面，Hasura 主要做了三件事：

1. 翻譯請求

• 你給它 GraphQL Query，它會幫你翻譯成底層的 SQL 查詢

2. 執行請求

• 它向資料庫發送 SQL，取得結果後回傳給你

3. 加上額外能力

• 例如自動生成角色權限檢查、支援即時訂閱（Subscription）、事件觸發器（Event Trigger）等。

這就是為什麼，Hasura 的價值不在於「存資料」，而在於「幫你省下後端開發的時間」。

那為什麼不直接用資料庫，還要多一層 Hasura？

很多人會問：「既然 Hasura 只是幫我下 SQL，那我直接操作資料庫不就好了？」

但 Hasura 的價值在於：它讓你省下手寫後端 API 的時間，並提供大量進階功能：

對於需要快速開發原型或維護大量業務資料的團隊來說，這是極大的優勢。

為什麼需要 Migration？

Hasura 除了生成 API，還需要幫你管理兩大類變更：

1. Database Migration（資料庫結構的變更）

• 新增 / 修改資料表、欄位、索引

2. Metadata Migration（API 設定的變更）

• 權限、Relationship、事件觸發器（Event Trigger）

如果只是單機開發，你可以隨便改；但在團隊合作或跨環境部署時，你就需要一套能「記錄、回滾、同步」的機制，這就是 Migration 存在的原因。

為什麼會有「本地」與「雲端」兩種版本？

Hasura 的歷史背景

初期：完全開源，只提供本地版

Hasura 2018 年以開源專案的形式問世，目標非常明確：

「讓開發者能在自己擁有的資料庫上，快速生成 GraphQL / REST API。」

在那個時候，Hasura 完全是給 技術團隊與開發者用的工具，典型的使用方式是：

1. 在自己的伺服器或本地環境，透過 Hasura CLI 搭配 Docker / Kubernetes 啟動 Hasura。
2. 把 Hasura 連接到自家資料庫（多為 PostgreSQL）。
3. 在開發過程中，Hasura 會自動幫你生成 Migration 檔案（up.sql、down.sql、metadata.yaml），方便你用 Git 做版本控制，並在 CI/CD 流程中自動同步到測試站、正式站。

這樣的工作流非常適合大型團隊與嚴謹的專案開發，因為它高度可控、可追蹤、可回滾。

但問題也很明顯——這對初學者來說太複雜了。

用戶需求的變化：大家想要「更快、更省事」

隨著 Hasura 開源社群的成長，許多新用戶不是專業後端工程師，而是：

• 想要快速做出產品雛型的前端工程師或獨立開發者
• 不想花時間維護伺服器的小型團隊或創業團隊

他們的需求跟企業用戶完全不同：

• 「我不想自己架設 Docker，也不想研究 Migration，只要能直接用就好。」
• 「我希望像 Firebase 一樣，打開瀏覽器就能操作。」

為了滿足這群「只求快速上線」的用戶，Hasura 官方在 2020 年左右推出了 Hasura Cloud（雲端 Console）。

雲端版的誕生

Hasura Cloud 的設計理念是：

「幫你托管好所有基礎設施，你只要專注在 API 與資料操作。」

因此：

• 不需要自己部署伺服器 → 官方已幫你托管
• 不需要關心 Migration → 所有操作都直接寫入資料庫與 Hasura Metadata
• 打開瀏覽器就能開始用 → 非常適合新手與快速驗證想法（MVP 開發）

這使得 Hasura 不再只是一個給專業後端用的工具，而是大幅降低了入門門檻。

設計理念的不同

Hasura 之所以同時保留 本地版與雲端版，是因為兩者面向的用戶需求完全不同。

本地版 (開源)

• 設計理念：以 Git 與自動化為中心
• 核心目標：適合嚴謹的專案開發，特別是多環境、多人的團隊
• 特點：
• 所有操作都會被檔案化（Migration 檔案、Metadata）
• 可進行版本控制與回滾
• 適合搭配 CI/CD，在多個環境保持一致
• 代價：需要自己部署與維護伺服器，學習成本較高

雲端版 (Hasura Cloud / Console)

• 設計理念：以快速體驗為中心
• 核心目標：適合快速開發、原型驗證、初學者
• 特點：
• 免部署、免維護 → 開箱即用
• 所有操作立即生效 → 不需要學習 Migration 工作流
• 非常適合短期專案或個人專案
• 代價：
• 缺乏版本控制 → 多人協作或跨環境同步困難
• 長期維護大型專案風險高

兩種版本的對比

本地 Hasura 環境：與檔案系統高度整合

什麼是 Hasura CLI？為什麼本地一定要用它？

Hasura CLI 是什麼？

Hasura CLI（Command Line Interface） 是 Hasura 官方提供的一套命令列工具，用來在本地開發環境中管理 Hasura 的各種操作。

你可以把它想像成 Hasura 的「遙控器」與「工作流管理員」，負責幫你：

1. 控制 Hasura

• 例如啟動本地的管理介面（Console UI）、連接資料庫、執行 Migration。

2. 生成檔案

• 自動幫你把所有資料庫結構變更、Metadata 設定，寫成 SQL 或 YAML 檔案，方便追蹤。

3. 部署同步

• 一鍵把本地變更套用到其他環境（例如測試站、正式站）。

✅ 簡單說：如果你要在本地「正式開發 Hasura 專案」，CLI 是不可或缺的核心工具。

為什麼本地一定要用 CLI？

Hasura 本地版的核心理念是：

「檔案才是真相（Files as the Source of Truth）」

這意味著任何改動都應該先寫成檔案，再同步到資料庫與 Hasura，以確保：

• 可追蹤 → 什麼時候改了什麼一目了然
• 可回滾 → 失敗時可用檔案快速回復
• 可同步 → 多人協作、跨環境保持一致

而這些功能，只有 CLI 能幫你做到。

如果你直接用 Hasura 伺服器自帶的 Console（或雲端版 Console），操作會直接寫入資料庫，不會留下檔案。

Hasura CLI 能做什麼？

以下是 CLI 最常見的用途與對應指令：

什麼是 Hasura Server？

很多初學者在第一次接觸 Hasura 時，會誤以為 Hasura 本身只是個「管理介面（Console）」或「本地工具」。

其實不然，Hasura 的核心是「Hasura Server」。

Hasura Server 是什麼？

Hasura Server 是一個常駐運行的服務，負責：

1. 連接你的資料庫（Postgres、MySQL、SQL Server…）
2. 自動生成 API（GraphQL / REST）
3. 處理來自前端或 CLI 的所有請求
4. 維護 Hasura Metadata（權限、Relationship、Event Trigger 等設定）

你可以把它想像成一個「智慧型 API 服務員」：

• 當有人發送 GraphQL 請求時，Hasura Server 會幫你把請求轉成 SQL，去資料庫抓資料再回傳結果。
• 當你在 Console（UI）上改動資料表或設定權限時，也是 Server 在後台執行對應的 SQL 或更新 Metadata。

✅ 一句話理解：Hasura Server 才是整個系統的「大腦」，而 CLI / Console 只是跟它互動的工具。

Hasura Server 跟 CLI 的關係是什麼？

• Hasura Server：
  • 持續運行，負責「真正執行操作」。
  • 當你要新增一個 Table、設定權限，最後還是要 Server 幫你執行。
• Hasura CLI：
  • 更像一個「中介人 & 秘書」。
  • 它會先幫你把所有操作記錄成檔案，再把請求轉給 Hasura Server執行。

✅ 比喻：

• Server = 廚師 → 真正煮菜（執行 SQL / GraphQL）。
• CLI = 負責點菜 & 記錄訂單的服務生 → 確保每道菜（操作）都有紀錄（檔案）。

Hasura Server 跟 Console（UI）的關係

Hasura 的 Console（UI）有兩種來源，差別在於「操作是否會先被記錄成檔案」：

所以，如果你要在本地進行正式開發、希望每一次變更都有 Migration / Metadata 紀錄，就必須用 CLI 啟動的 Console。

接下來我們深入看看 「為什麼 CLI Console 能做到這件事？」

用 CLI 開啟的 Console，才會生成檔案

CLI 為什麼能生成檔案？

當你在專案目錄執行 hasura console 時，CLI 會啟動一個本地代理服務（Proxy），用來「攔截」並「加工」你在 UI 上的每一個操作。流程如下：

1. 攔截請求

• 例如你在 UI 點「Add Table」時，這個請求不會直接送到 Hasura Server，而是先被 CLI Proxy 接收。

2. 生成檔案

• CLI 會在 migrations/ 資料夾中自動生成 up.sql / down.sql，並在 metadata/ 更新相應的 YAML。

3. 再轉發給 Hasura Server

• 檔案生成後，CLI 才會將請求送給 Hasura Server，讓資料庫和 Hasura Metadata 實際更新。

✅ 流程示意圖：

graph TD
    A[在 Console UI 點 Add Table] --> B[CLI Proxy 攔截請求]
    B --> C[生成檔案<br/>migrations/*.sql<br/>metadata/*.yaml]
    B --> D[寫入檔案系統]
    D --> E[轉發給 Hasura Server]
    E --> F[資料庫 & Metadata 更新]

    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#f1f8e9
    style D fill:#e8f5e8
    style E fill:#fff3e0
    style F fill:#e1f5fe

操作步驟：完整流程

以下是本地開發的標準步驟：

1. 啟動 Hasura 專案

   docker-compose up -d

（確保 Postgres / Hasura Server 正常運行）

2. 啟動 CLI Console

   hasura console

預設會開啟 http://localhost:9695（CLI Proxy）。

3. 在 Console UI 上操作

• 新增 Table、欄位
• 設定 Relationship / 權限

4. 檢查檔案是否生成

• migrations/ 資料夾中應出現新的 <timestamp>_<name> 子資料夾
• metadata/ 會更新相關設定

5. 將檔案推送到 Git，便於版本控制

   git add migrations/ metadata/
   git commit -m "add user table"

新手常見問題

1. 「我明明用 localhost 的 UI 改了東西，為什麼沒生成檔案？」

• 檢查你是不是直接用 Server 自帶的 Console (8080/console)
• 正確做法是：執行 hasura console → 用 CLI Proxy 的 9695 端口

2. 「為什麼 up.sql 是空的？」

• 如果你改的是 Metadata（例如新增 Relationship、設定權限），就只會生成 YAML，不會有 SQL。

3. 「檔案名稱亂七八糟，看不懂？」

• CLI 會用「時間戳 + 操作名稱」自動生成，例如： migrations/ 1721891234567_create_user_table/ up.sql down.sql

CLI 會生成什麼檔案？

在本地開發時，Hasura CLI 的最大特點，就是會把所有「結構或設定的變更」自動轉換成檔案，存放在專案中，方便後續進行 版本控制、回滾、跨環境部署。

Hasura CLI 主要會生成兩種類型的檔案：

Database Migration 檔案

這是用來記錄資料庫層級的結構變更。

每當你對資料表或欄位結構做操作，例如：新增 Table、增加欄位、刪除索引，CLI 都會生成一組新的 Migration 資料夾。

檔案組成：

• up.sql → 做變更的 SQL 腳本
• down.sql → 回滾變更的 SQL 腳本（例如 DROP Table、刪除欄位）

資料夾命名規則：

migrations/
  <timestamp>_<name>/
    up.sql
    down.sql

• timestamp：13 位數的 UNIX 時間戳（精確到毫秒），確保順序性
• name：你執行操作時 CLI 自動生成的名稱（或你手動輸入）

範例：

migrations/
  1721887654321_create_user_table/
    up.sql        # CREATE TABLE user (id UUID PRIMARY KEY, name TEXT, ...)
    down.sql      # DROP TABLE user

常見的 SQL 內容：

• 新增 Table → CREATE TABLE ...
• 新增欄位 → ALTER TABLE ... ADD COLUMN ...
• 新增索引 → CREATE INDEX ...

Metadata Migration 檔案

Hasura 除了管理資料庫結構，還會自動維護 Hasura 特有的設定，這些設定與 SQL 無關，因此會以 YAML 檔案形式存放。

會被記錄的設定包括：

• 權限（Permissions） → 哪個角色可以查詢/新增/更新/刪除哪些欄位
• Relationship → Hasura 自動生成的關聯設定
• Event Triggers → 當資料變動時，觸發 Webhook 的設定
• Remote Schema / Actions → 與其他 API 整合的設定

檔案結構：

metadata/
  databases/
    default/
      tables/
        public_user.yaml   # 記錄 user 表的所有 Metadata，如權限 & Relationship
  actions.yaml
  cron_triggers.yaml
  version.yaml

範例（public_user.yaml 可能包含的設定）：

table:
  schema: public
  name: user
select_permissions:
  - role: user
    permission:
      columns: ["id", "name"]
      filter: {}
object_relationships:
  - name: profile
    using:
      foreign_key_constraint_on: profile_id

檔案生成的時機

Hasura CLI 會在以下情況下生成檔案：

✅ 小結：

• SQL 結構變更 → migrations/
• Hasura 設定變更 → metadata/
• 兩者同時發生 → 兩個資料夾都會更新

檔案的實際用途

這些檔案的存在，讓你可以：

1. 版本控制

• Git 追蹤每一次變更，誰改了什麼一目了然

2. 回滾

• 透過 CLI 執行 hasura migrate apply --down 1 就能回到上一個版本

3. 跨環境同步

• 在 CI/CD 中一鍵部署 hasura migrate apply --endpoint=$PROD_URL hasura metadata apply --endpoint=$PROD_URL

檔案結構完整範例

假設你在 UI 上新增一張 user 表並設定基本權限，專案會多出以下結構：

migrations/
  1721887654321_create_user_table/
    up.sql        # CREATE TABLE user (id UUID PRIMARY KEY, name TEXT)
    down.sql      # DROP TABLE user

metadata/
  databases/
    default/
      tables/
        public_user.yaml     # Hasura 設定：權限、Relationship
  version.yaml

適用場景

因為本地 Hasura 強調「版本控制」與「跨環境一致性」，它非常適合正式專案與多人協作。

多人協作開發

• Git 追蹤：所有 Migration 與 Metadata 檔案都能被 Git 追蹤，團隊成員可以透過 Pull Request 清楚檢視彼此的改動。
• 避免衝突：因為所有改動都以檔案形式存在，不會出現「某個同事在資料庫直接改了欄位，導致其他人環境不一致」的情況。

跨環境部署

• 典型流程：

1. 在本地開發 → Hasura CLI 生成 Migration 檔案
2. 推送到 Git → CI/CD 會讀取這些檔案
3. 在測試站或正式站執行 hasura migrate apply → 自動同步相同變更

• 環境一致性保障：每個環境都使用同一套 Migration，避免測試環境與正式環境的 Schema 不一致。

不適用的場景

反過來，如果只是想快速試驗或是個人短期專案，本地 Hasura 反而顯得「太重」。

因為：

• 你必須學會 CLI、Docker 的基礎操作
• 每次改動都需要生成檔案再套用，無法像雲端 Console 那樣即改即用

雲端 Console：直接操作即時生效

運作機制

雲端 Console 是什麼？

Hasura Cloud Console（通常簡稱 雲端 Console）是一個由 Hasura 官方托管的管理後台。

你不需要自己部署 Hasura Server，只要註冊帳號、綁定資料庫，打開瀏覽器就能直接使用。

✅ 一句話理解：它更像 Firebase 這類雲端後台服務，重點是「即時方便」而不是「可版本控制」。

運作邏輯：為什麼不會生成檔案？

在雲端 Console 中，你的所有操作都是直接呼叫雲端上的 Hasura Server API，例如 /v1/metadata 或 /v2/query，因此：

1. 直接修改資料庫 / Metadata

• 例如你在 UI 上新增 Table，Hasura Server 會立刻對底層資料庫執行 CREATE TABLE SQL。

2. 不會經過 CLI Proxy

• 因為沒有 CLI，「檔案生成」這個步驟完全被省略。
• 你在本地專案資料夾裡也不會看到任何 migrations/ 或 metadata/ 的更新。

3. 操作即時生效

• 改完立刻生效，無需額外執行 hasura migrate apply。

✅ 流程示意圖：

graph TD
    A[在 Console UI 點 Add Table] --> B[直接打到 Hasura Server]
    B --> C[資料庫 & Metadata 更新]
    B --> D[不生成任何檔案]

    style A fill:#e3f2fd
    style B fill:#ffcdd2
    style C fill:#e1f5fe
    style D fill:#ffebee

這種即時操作很方便，但長期來看，會讓環境之間難以保持一致。

雲端 Console vs 本地 CLI：核心差異

適用場景

雲端 Console 的定位是**「快速、簡單」**，適合以下場景：

原型開發與快速驗證（MVP）

• 你可以直接在雲端 Console 中幾分鐘內就完成一個 API 的建置，非常適合：
• 初期測試產品概念
• Hackathon 或快速交付原型

臨時調整正式環境的小問題

• 例如：
• 緊急開放某個角色的權限
• 快速增加一個臨時使用的 Table
• 在無法等候完整 CI/CD 流程時，雲端 Console 是最快的解決方案。

不適用的場景 & 風險

雲端 Console 不適合用於長期維護的正式專案，原因如下：

1. 無法保證環境一致性

• 你在雲端直接操作後，本地或測試環境無法自動同步。
• 團隊成員需要手動「複製操作」，非常容易出錯。

2. 缺乏版本控制

• 改動不會以檔案形式保留下來，無法使用 Git 追蹤，也無法回滾到舊版本。

3. 多人協作困難

• 團隊成員無法在 Pull Request 中 review 你的 Schema 變更。

✅ 結論：雲端 Console 適合短期與單人開發，但如果專案需要長期維護，一定要盡早轉向本地 CLI 版工作流。

總結

• 本地 Hasura 是一個以「版本控制與跨環境部署」為核心設計的工作流，所有操作都會轉化為檔案，方便追蹤與自動化。
• 雲端 Console 則像是一個「管理後台」，適合快速測試與臨時修改，但不適合長期團隊協作。

如果你要開始正式的 Hasura 專案，建議盡早熟悉本地 Migration 流程，讓你的專案更穩定、更容易維護。