Release 與 Revision

兩個常被搞混的名詞：

	Release	Revision
是什麼	一組變更的凍結版本	已實際施加到 DB 的變更紀錄
時機	提早凍結，準備多環境推進	執行成功後產生
對象	Project（含多個 DB）	單一 Database
可改？	凍結後內容不可改	append-only
用途	版本管理 / 多環境推進	「這個 DB 已經到哪版」

Release

是什麼

把一個 project 在某時間點要推的所有變更打包，標上版本。之後可以：

• 推到 staging → 驗證 → 推到 prod
• 在不同環境追蹤「目前在哪版」
• 回溯：歷史上哪個 release 改了什麼

結構

Release v1.4.0
 ├─ Migration 001: add idx_orders_user_id (DDL)
 ├─ Migration 002: backfill orders.region (DML)
 └─ Migration 003: drop deprecated column orders.legacy_id (DDL)

每個 migration 對應一段 SQL + 元資料。

生命週期

draft ──> published ──> archived

狀態	含意
draft	編輯中
published	已凍結；內容不可改；可被各環境引用推進
archived	已下線；不能再用於新 rollout

與 Plan / Issue / Rollout 的關係

一個 published Release 可被多個 Issue 引用：

Release v1.4.0 (published)
   │
   ├─── Issue #501 (dev → done)
   ├─── Issue #502 (staging → done)
   └─── Issue #503 (prod → in approval)

每個 Issue 自帶完整審批流程，但 SQL 內容統一來自 Release。

為何要 Release

痛點	Release 怎麼解
同一變更在三個環境跑，每次都複製貼上	凍結一次，引用多次
環境間版本不一致，沒人知道 prod 缺什麼	Release ID 對映到每個 DB 的 revision
緊急 hotfix 之後忘記補回低環境	Release 提供 reconcile 機制

不變式

• Published 的 Release 內容不可改。要改 → 發新 Release（v1.4.1）
• Release 屬於 Project，不可跨 Project 引用
• Release 的 migration 順序固定，依序套用

Revision

是什麼

「這個 DB 已經施加過哪些變更」的歷史紀錄。每執行成功一個 Task，就會在目標 DB 上產生一筆 Revision。

結構

每筆 Revision：

欄位	說明
database	哪個 DB
version	對應的 Release version（如 v1.4.0-001）
sheet	真正執行的 SQL 內容（凍結快照）
applied_at	套用時間
applied_by	觸發者
task_run	對應的 TaskRun

怎麼用

• diff：對比兩個 DB 的 revision 差異 → 「staging 跑了什麼 prod 沒跑」
• drift detection：DB 上實際 schema vs revision 應有 schema 不符 → 報警
• 稽核：「2026-04 prod.orders 改了哪些 schema？」直接讀 revision

不變式

• Revision append-only：永不更新、永不刪除
• 若需要回滾，不是刪 revision，而是新增一筆反向 revision
• Revision 與 task_run 一對一

一張圖看清楚

Project
 │
 ├─ Releases (凍結的版本)
 │    ├─ v1.4.0  (published)
 │    │    ├─ Migration 001
 │    │    ├─ Migration 002
 │    │    └─ Migration 003
 │    └─ v1.4.1  (published)
 │
 └─ Databases
      ├─ dev.orders     ── Revisions: [v1.4.0-001, v1.4.0-002, v1.4.0-003, v1.4.1-001]
      ├─ staging.orders ── Revisions: [v1.4.0-001, v1.4.0-002, v1.4.0-003]
      └─ prod.orders    ── Revisions: [v1.4.0-001, v1.4.0-002] ← 還沒推完

從這張圖可以一眼看出：prod.orders 落後 staging 兩個 migration、落後 dev 三個。

UI 上的位置

• Release：Projects → <p> → Releases
• Revision：Database 詳情頁的 Revisions tab

對應 store

• 表：release（複合 PK (project, id)）、revision
• proto：argus.v1.Release、argus.v1.Revision

相關

• Plan、Issue、Rollout
• Task 與 TaskRun
• Composite-PK 表清單
• 任務：Release 與版本回溯