Release 與版本回溯

何時用這份文件 你要在多個環境推同一組變更、要查某 DB 落在哪版、要補登手動執行的變更、或要做版本對齊。

前置條件

• 角色：workspaceDBA 或 projectOwner
• 已讀過 Release 與 Revision

場景對照

你想做的事	走
把一組變更打包，分階段推 dev → staging → prod	Publish Release
某個 DB 落後 staging，要補上	推進落後環境
查 prod 上的 schema 是來自哪幾個 Release	Revision 軌跡
手動在 DB 做了變更，要補進 Argus	補登 revision
整版回滾（包括所有 task）	整版回滾

Publish Release

把 project 內準備好的變更打包成版本。

步驟

1. Projects → <p> → Releases → New Release

2. 填：

   • Version：v1.4.0（建議 semver）
   • Description：包含哪些變更、為什麼、相關 ticket

3. 加 Migrations（每個對應一段 SQL + 元資料）

   001  add_idx_orders_user_id    DDL
   002  backfill_orders_region    DML
   003  drop_legacy_id_column     DDL

4. 各 migration 跑一遍 plan check（同 Plan Check）

5. 全綠 → Publish

一旦 published，內容凍結。要修 → 發新版（v1.4.1）。

引用 Release 開 Issue

每個目標 environment 開一個 Issue，引用同一個 Release：

# 例：對 staging 推 v1.4.0
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{
    "title": "Release v1.4.0 → staging",
    "release": "projects/play/releases/v1.4.0",
    "environment": "environments/staging"
  }' \
  "$ARGUS/v1/projects/play/issues"

每個 environment 仍走自己的審批 + Rollout（不會跳過審批）。

推進落後環境

看哪些 DB 落後

Projects → <p> → Releases → <release> → Status：

v1.4.0 status
  ├─ dev.orders      ✅ applied
  ├─ staging.orders  ✅ applied
  └─ prod.orders     ⏳ pending

或從 Database 詳情頁的 Revisions tab 看 reverse view（這個 DB 收到哪些 Release）。

推進

對 pending 的 environment 開 Issue（同上），走完整審批 + rollout。

不要直接 mark 為 applied — 那會破壞 revision 真實性。

Revision 軌跡

查單一 DB 的歷史變更：

# UI
Databases → <db> → Revisions

# API
curl -s -H "Authorization: Bearer $TOKEN" \
  "$ARGUS/v1/projects/play/databases/prod.orders/revisions?orderBy=appliedAt desc" \
  | jq '.revisions[] | {version, appliedAt, appliedBy, taskRun}'

每筆 Revision 包含：

• version — 對應的 Release migration（如 v1.4.0-001）
• applied_at / applied_by
• sheet — 當時實際執行的 SQL（凍結快照）
• task_run — 對應 TaskRun（可點進去看 log）

跨 DB diff

Databases → diff：選兩個 DB，看 revision 差異。輸出可以匯出成清單，當作對齊計畫。

補登 revision

你手動在 DB 做了變更（緊急修補、外部 migration tool 跑的）— 要讓 Argus 知道。

方法 A：建一個「已執行」的 task

1. 開 Plan，內容貼上手動執行的 SQL
2. 開 Issue，descriptio明寫「補登」
3. Rollout 時對對應 task 點 Mark as Applied（不真的執行）

方法 B：直接 import revision

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{
    "version": "manual-2026-05-24",
    "sheet": "ALTER TABLE orders ADD COLUMN ...",
    "appliedBy": "user/login_id=alice",
    "note": "Emergency hotfix during 2026-05-24 incident #1234."
  }' \
  "$ARGUS/v1/projects/play/databases/prod.orders/revisions:import"

兩種方法都會寫 audit log，含 actor + 理由。沒有「悄悄補登」這個選項。

整版回滾

對整個 Release 反向操作。非常少見，多數情況走 緊急回滾 對單一變更。

流程

1. 開新 Release（反向版本），命名 v1.4.0-revert
2. 內容是 v1.4.0 每個 migration 的反向 SQL（人工確認）
3. 走完整 plan check + 審批
4. 對需要回滾的環境開 Issue → 跑 Rollout

⚠️ 反向 SQL 由 DBA 親自確認。不要信任 Argus 自動產生的 reverse SQL — 那只是起點，需要對著當時實際發生的事情調整。

為什麼這麼麻煩

因為「回滾」對 DB 來說通常不存在：

• 加索引可逆 → drop index
• 加欄位可逆 → drop column（但欄位裡的資料就沒了）
• DML 不可逆 → 需要備份還原
• DROP table 不可逆 → 從備份還原

如果回滾要從備份還原 → 屬於 備份與災備 場景，不是 Release-level 動作。

不要做的事

反模式	為什麼
不發 Release，每個 DB 各開 Plan	沒辦法跨環境追蹤、容易遺漏
把 staging hotfix 跳過 dev 直接推 prod	環境會永久失同步；之後 dev 跑某 SQL 會炸
手動執行後不補登 revision	之後 diff 永遠看不一致；事後稽核找不到 actor
把過期的 Release 不 archive	UI 列表雜亂、誤選舊版本
自己發明版本號（fix-1234）	無法排序、無法 diff、未來自己也忘

相關

• 概念：Release 與 Revision
• 上游：執行一個 rollout
• 出事：緊急回滾、備份與災備
• 重試：中止 / 重試 task