執行一個 rollout

何時用這份文件 Issue 已通過審批，狀態為 Approved，需要 DBA 啟動 Rollout 並監看執行過程。

前置條件

• 你的角色擁有 bb.rollout.execute（不確定 → 看 指派角色與權限）
• 你已讀過該 Issue 的描述、SQL、plan check 結果
• 你已確認現在是合適的執行時機（不在凍結期、不在業務高峰）

凍結期 / 高風險窗口政策請見 高風險變更窗口。

執行前 60 秒檢查

⏱ 花 60 秒走一次以下清單，比事後處理事故快 100 倍。

• [ ] Issue 狀態 = Approved（不是 Open 或 Canceled）
• [ ] Plan Check 沒有未解決的 error
• [ ] 目標 environment / instance / DB 與 Issue 描述一致
• [ ] 估算影響範圍與業務 owner 已對齊
• [ ] 若是 prod：已通知 #ops 頻道
• [ ] 已知道怎麼回滾（不是「應該可以回」）

任一項打勾不下去 → STOP，補齊或改開 緊急變更窗口。

步驟

1. 進入 Issue → Rollout 頁

Projects → <project> → Issues → <issue id>，下半部會看到對應的 Rollout 區塊（issue 在 approve 那一刻就會自動建好 rollout，初始狀態 pending）。

2. 檢視拆解後的 Task 列表

Rollout 會依 Plan 的 target 拆成多個 Task，每個 task 對一個 DB。

欄位	看什麼
Target	預期的 DB 沒少 / 沒多
SQL preview	真正要跑的 SQL（含 schema substitution）
Estimated rows	plan check 估算的影響 row 數
Order	任務執行順序（dev → staging → prod）

如果 task 順序不符合你期待，不要直接跑。在 Rollout 上調整 task 階段（Stage），或回頭請開發者調整 Plan target。

3. 啟動 Rollout

• 全部一次跑 → 按 Run
• 分階段跑（推薦）→ 按 Run stage，跑完一階確認再下一階
• 排程跑 → 按 Schedule，選時間（適合凌晨變更）

4. 監看執行

進入 task 詳情看：

• 即時 log（含 server-side log + DB driver log）
• 執行中的 SQL（current statement）
• 已耗時
• 鎖等待 / 阻塞狀態（若 driver 支援）

同時建議在另一個視窗開 DB 端的監控（pg_stat_activity、慢查詢、replication lag），雙路觀察。

5. 處理失敗（如發生）

• 看 task run 的 stderr / error message
• 若是暫時性錯誤（網路抖動、deadlock）→ Retry（會建立新的 TaskRun，舊的保留）
• 若是邏輯錯誤（SQL 本身寫壞）→ 不要 retry；走 中止 / 重試 task 或 緊急回滾

⚠️ Retry 的前提是「重跑同一段 SQL 是安全的」。對非 idempotent 的 SQL（INSERT INTO ... VALUES ...、ALTER TABLE ADD COLUMN 已成功但 commit 失敗）謹慎評估。

6. 完成後驗證

• Rollout 狀態 = Done
• 所有 task 狀態 = Done
• 直接連目標 DB 確認變更生效
• 在 Issue 留 comment：「✅ Rollout 完成，schema/資料已驗證。」
• 通知 #ops 頻道（如果 prod）

驗證

# 取得 rollout 完整狀態
curl -s -H "Authorization: Bearer $TOKEN" \
  "$ARGUS/v1/projects/<proj>/rollouts/<id>" | jq '.state, .tasks[] | {target, state, taskRuns}'

預期 state == "DONE"，每個 task 至少有一個 taskRun.state == "DONE"。

Audit log 篩條件 resource = rollout/<id>，應該看到從 started 到 done 的完整時間軸。

常見錯誤

症狀	原因	排除方式
Run 按鈕灰掉	Issue 還沒 approved / 你沒權限	看 Issue 狀態；補審批 / 補權限
Task pending 很久不啟動	task scheduler 未拉取	看 server log；確認 taskrun-scheduler runner 正常
Task running 很久不結束	鎖等待 / 大表掃描	看 DB 端 pg_stat_activity
Retry 後仍失敗	邏輯錯誤 / 環境差異	走 中止 / 重試 task
Prod rollout 後業務指標異常	變更副作用	立刻走 緊急回滾

相關

• 拆解：Rollout / Task / TaskRun
• 出事：緊急回滾
• 重試：中止 / 重試 task
• 版本：Release 與版本回溯