用 AdminExecute 緊急直跑

何時用這份文件 Prod 出狀況、Plan 流程走不通、必須在幾分鐘內手動執行 DDL / DML。這是 Argus 唯一不經 Plan 審批就能執行寫操作的入口，必須謹慎且事後補單。

一般狀況下不要用 AdminExecute。走 Plan 流程：執行一個 rollout。

是什麼

SQL Editor 切到 Admin 模式後，編輯器底部 Run 按鈕變成「使用 admin data source 直接執行」。對應 RPC 是 argus.v1.SQLService/AdminExecute（BidiStream，每個 statement 一個 response）。

跟 Query 的差別：

	Query	AdminExecute
可執行類型	SELECT only	DDL / DML / SELECT 全
Data source	read-only（若有）或 admin	永遠 admin
串流	一次回傳	每 statement 一筆 response
Advisor	跑（observable-only）	跑（observable-only）
Masking	套用	套用（但 DDL 通常不回 row）
Audit	記	記

前置條件

• 角色含 bb.databases.adminExecute（多半 workspaceDBA 或 projectOwner）
• 目標 instance 已配置 admin data source（不是只有 read-only）
• 事件已經啟動（incident、page、值班）— 不要把 AdminExecute 當開發捷徑

決策樹 — 何時可以直跑

執行前 30 秒儀式

每次 Run 前對自己念一遍：

1. 這條 SQL 跑下去最壞會怎樣？ — 想出 worst case
2. 能還原嗎？ — 有沒有 backup / PITR / 軟刪 flag？
3. 影響範圍：哪些 table、多少 row、有沒有觸發器、有沒有外鍵 cascade
4. 時間視窗：rate-limit、業務尖峰、跟其他 batch 衝突嗎
5. 公告了嗎：值班 IM、SRE channel

如果有任一項答不出來，停下來。

跑下去的步驟

1. SQL Editor 左下 mode toggle → Admin（紅色標記）
2. 選對 instance + database（對兩次）
3. 編輯器輸入 SQL（單一語句比較好控制）
4. Run
5. 看回應區的 result + advisor banner

多語句 BidiStream：每跑完一條 stream 一筆 response。若中間出錯，已執行的不會 rollback（除非你自己 BEGIN; ... COMMIT;）。

結果回應的判讀

Result 區

欄位	含意
rowsAffected	DML 影響的 row 數（DDL 通常 0）
latency	真實執行時間（不含 advisor、masking）
error	驅動層錯誤訊息

DDL 通常無 row 回，看 error 是否為空判斷成功。

Advisor banner

跟 Query 一樣會跑 advisor（observable-only）。對 AdminExecute 來說 advisor 是一個「跑前的二次確認」：你正在繞 Plan 流程，advisor 提醒「你還是踩到了某條規則」。

不會擋；但若 banner 顯示 ERROR 等級規則，停下來想想是不是真的非跑不可。

Masking 提示

DDL 通常無資料 row；DML / SELECT 有時 row 被 masking 替換。這不是錯誤，是 sensitive data policy 在保護你看不該看的東西。

執行後 5 分鐘儀式

1. 驗證 DB 真實狀態：用同樣 instance 跑 SELECT 確認結果（不能只看 AdminExecute 的 echo）
2. 告知值班 IM：「事件 ID #N，跑了 X，影響 Y row」
3. 看 audit log：確認 bb.databases.adminExecute event 已寫入（查詢 audit log）
4. 看 advisor violation：上 audit log 查 method=/argus.v1.SQLService/AdvisorViolation 確認是否有違規該事後 follow up
5. 補單：事件結束後 24h 內，寫一個 retroactive Plan 把這次手動執行記入 Release / Revision（讓 schema state 與平台帳本一致）

第 5 條（補單）是公司 SOP 的硬性要求 — 沒補單的緊急執行會在 month-end audit 被列為 finding。

⚠️ 跑了 DDL（schema 變更）後 10 分鐘內你會在 Sidebar 看到一筆 Schema 漂移事件。這是 Schema Drift Detection 在工作 — runner 偵測到 DB 真實 schema 跟 Plan-blessed baseline 不一致就會寫事件。正常流程：補 retroactive Plan → Plan 通過 → TaskRun 自動祝福新 baseline → 下次 runner tick 不再出現此 event。如果你拖延沒補單，drift event 會一直留著被 auditor 看到。詳見 處理 drift event。

反模式 — 看到立刻喊停

行為	為什麼不該
用 AdminExecute 跑 ad-hoc 查詢	該用 Query mode（read-only data source、更安全）
為了「比較快」用 AdminExecute 取代 Plan	Plan 反正幾分鐘就過，你省不下時間，但失去回滾與審批保護
在 AdminExecute 跑「實驗性」 SQL 看會怎樣	用 dev environment 或本地 sandbox
多人同時對同 DB 跑 AdminExecute	race condition + audit log 變模糊；用 incident channel coordinate
BEGIN; ... COMMIT; 包大段 SQL	BidiStream 中途斷線會留 open transaction；用單句或自寫 idempotent script

常見錯誤

訊息 / 現象	含意	處理
failed to get database driver: ...admin data source not found	instance 沒配 admin data source	找 workspace admin 配；不要繼續
permission denied for relation X	DB-level 權限不夠	連到 DB 直接 GRANT；或換有權的 DBA
connection terminated unexpectedly	中途斷線；可能 partial commit	立即連 DB 驗證真實狀態
Advisor banner 顯示 ERROR	你踩到 advisor 規則	不擋，但 review 一下；事件結束後可能要修
AdminExecute 完成但 bb.databases.adminExecute 沒寫進 audit log	異常 — 平台 bug	抓 slog、上報

跟 Plan 流程的補單範本

事件結束後跑這個 Plan（標題範本）：

[Retroactive] Incident #N — manually executed via AdminExecute on YYYY-MM-DD

SQL（與當時一致）:
<貼上實際跑的 SQL>

緣由:
- 事件 ticket: #N
- 為什麼不能走 Plan: <說明，例：「Plan check 卡 5 分鐘以上、Prod 持續燃燒」>
- 影響範圍: <table / row count>
- 執行者: <你>
- 執行時間: YYYY-MM-DD HH:MM TZ
- IM 通知記錄: <連結>

此 Plan 走加速審批（DBA Lead + 主管）；通過後該變更納入 Release / Revision 帳本，月底 audit 不再列 finding。

相關

• 概念：SQL Editor
• 概念：Plan、Issue、Rollout
• 任務：執行一個 rollout（正常 Plan 路徑）
• Runbook：緊急回滾
• Runbook：二線值班接手
• Auditor：查詢 audit log