提交第一個變更

何時用這份文件 你剛跑起 Argus、接好一個測試 Postgres，想把整套變更流程走過一次，把 Plan / Issue / Rollout 那些名詞變成肌肉記憶。

前置條件

• 已完成 安裝與啟動
• 已完成 建立第一個 Instance
• 你在這個 instance 下有一個資料庫，例如 playground

步驟

1. 開啟一個 Plan

從左側 sidebar 進入 Projects，挑一個 project，點 New Plan。

填入：

欄位	範例值
Title	加上 users.email 唯一索引
Target	選擇 playground 資料庫
Change type	Schema migration
SQL	sql<br/>CREATE UNIQUE INDEX CONCURRENTLY idx_users_email ON users(email);

為什麼是 Plan 而不是直接執行？ Plan 是「我想做這件事」的宣告，還沒真的執行。它讓 Argus 有機會先跑 plan check、收集審批、安排執行窗口。

按 Create。

2. 看 Plan Check 跑完

Plan 建立後，Argus 會自動觸發 Plan Check：

• 語法檢查
• 影響範圍估算（這個 index 會掃多少 row）
• 命名規範
• 高風險動作偵測

預期看到 4 個 check 全綠。

如果有 warning / error：

• ✅ Warning：可以選擇繼續或修正
• ❌ Error：必須修正才能進下一步

3. 由 Plan 建立 Issue

Plan 通過檢查後，點 Create Issue。Issue 是「這件事正在被處理」的單據，會啟動審批流程。

選擇審批者（或讓 Argus 依照 environment 規則自動指派）。

4. 審批

切換成審批者角色（在測試環境可以用同帳號 self-approve；正式環境會由 Lead / DBA 來做）。

點 Approve。

對應主管要求 ① 審計 + ②零信任：每個 approve 動作都會寫進 audit log，actor / target / timestamp 都會保留。

5. 執行 Rollout

審批完成後，Issue 會變成 Rolloutable。點 Run 觸發 Rollout。

Rollout 會把這個變更拆成 Task，每個 task 對一個資料庫。每跑一次就是一個 TaskRun（所以同一個 task 可能有多筆 task_run，例如重試）。

6. 看 TaskRun 結果

Rollout 頁面上會即時顯示每個 task 的：

• 狀態（pending / running / done / failed）
• 執行 SQL
• 執行時長
• 影響 row 數
• 完整 log

預期看到 done，並且 users 表上多了 idx_users_email。

驗證

直接到 Postgres：

psql -U postgres playground -c "\d users"

應該看到新加的 idx_users_email 索引。

回到 Argus，左側選 Audit Log，篩選最近 10 分鐘。應該看到：

• Plan created
• PlanCheckRun completed
• Issue created
• Issue approved
• Rollout started
• TaskRun completed

每一筆都會有 actor、target、timestamp、result。

常見錯誤

症狀	原因	排除方式
Plan check 一直 pending	advisor pool 未啟動	確認 server log 沒有 advisor 啟動失敗訊息
Approve 按不下去	當前 environment 沒設定 approver policy	admin 到 Settings → Environment 補上 approver
Task run 卡 running	後端對 instance 連不上	檢查 instance 的網路 / credentials
看不到 audit log	你的角色沒有 bb.auditLog.read	請 admin 補權限

你剛剛學到的概念

概念	一句話
Plan	「我想做這個變更」
PlanCheckRun	Argus 對 Plan 跑的自動體檢
Issue	「這個變更正在被處理」的單據
Rollout	把 Plan 真的施加到資料庫的執行流程
Task	一個資料庫上的一個變更動作
TaskRun	Task 的一次執行（可能重試多次）

要深入了解：領域模型。

下一步

• 想看自己 vs 別人提的 plan：查看 plan check 結果
• 想了解審批怎麼設計：審批流程
• 把 Argus 從玩具變成生產：私有部署