提交一個 SQL 變更

何時用這份文件 你拿到一個需求（加欄位、調索引、改資料），想透過 Argus 把這個變更安全地推到目標資料庫。

前置條件

你的帳號已被加入該 project（不確定 → 問 workspace admin）
你知道目標資料庫名（例：order_service instance 的 orders DB）
你有 SQL 變更內容（未壓縮 / 未拼接 / 未編碼，純 SQL）
如果是高風險動作（DDL on prod、大表 DML、drop column），請先讀高風險變更的判斷準則

步驟

1. 進入 project，按 `New Plan`

Projects → <your project> → 右上 New Plan。

2. 填寫 Plan 內容

欄位	說明	範例
Title	一句話講你為什麼做，不是做什麼	`修正訂單超賣 — 在 orders.user_id 加索引`
Target	選資料庫；可多選同 project 下的 DB	`prod.orders`、`prod.orders_archive`
Change type	`Schema migration` / `Data change` / `Migration with DML`	`Schema migration`
SQL	真實要執行的 SQL	見下方

sql

-- 用 CONCURRENTLY 避免鎖表
CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders(user_id);

不要把多個邏輯獨立的變更塞到同一個 Plan。一個 Plan 對應一個邏輯目標，方便回滾、方便審批者理解、方便事後追溯。

按 Create。

3. 等 Plan Check 跑完

建立後 Argus 會自動啟動 Plan Check：

Check	在看什麼
Syntax	SQL 能不能 parse
Schema impact	影響哪些 table / column
Naming	命名規範（依 workspace 規則）
Risk	高風險動作偵測（drop / truncate / 全表 update）

全綠 → 進下一步 Warning → 看細節，必要時補說明 Error → 改完 SQL 重跑

4. 由 Plan 建 Issue

Plan 通過後，點 Create Issue。Argus 會依 environment policy 自動指派審批者（你也可以加額外 reviewer）。

撰寫 Issue 描述時，建議包含：

背景：為什麼這個變更必須做（連到 ticket / 事件單）
影響範圍：哪些服務會用到、預估執行時長、是否需要停機
回滾計畫：如果失敗怎麼辦
驗證計畫：上線後怎麼確認 OK

5. 等審批

審批者可能會在 Issue 上留 comment 要你補資訊或改 SQL。在 Issue 上回覆 / 修正 / 重新跑 plan check。

已 issued 的 Plan 不能改 SQL 本身；要改 SQL 必須開新 Plan。Issue 的 comment 屬於協作層，不影響執行內容。

6. Rollout 啟動

審批通過後，預設由 DBA 角色手動啟動 Rollout（依 environment policy）。你會在 Issue 上看到狀態變化，並收到通知。

7. 追蹤執行

進入 Rollouts → <rollout id>，看每個 task 的：

狀態（pending → running → done / failed）
實際執行的 SQL（含 transaction 邊界）
執行時長
影響 row 數
完整 stdout / stderr

驗證

執行完成後：

直接連目標 DB，確認你預期的 schema / 資料變更已生效
Audit log 上應該有完整的時間軸：plan created → check done → issue approved → rollout done

常見錯誤

症狀	原因	排除方式
找不到目標 DB	該 DB 還沒 transfer 到你的 project	請 DBA / admin 做 transfer
Plan check 顯示 `naming violation`	SQL 命名不符合 workspace 規則	改名 / 找 admin 調整規則
Issue 卡 `waiting for approval` 很久	沒設審批者 / 審批者休假	在 Issue 上 @ 一個替代審批者
Rollout 失敗，task 卡 `running`	目標 DB 連不上、權限不足、鎖等待超時	看 task run log；多半要 DBA 介入
我要改 SQL，怎麼辦？	Plan 已 issued	開新 Plan，舊 Issue cancel

提交一個 SQL 變更 ​

前置條件 ​

步驟 ​

1. 進入 project，按 New Plan ​

2. 填寫 Plan 內容 ​

3. 等 Plan Check 跑完 ​

4. 由 Plan 建 Issue ​

5. 等審批 ​

6. Rollout 啟動 ​

7. 追蹤執行 ​

驗證 ​

常見錯誤 ​

相關 ​