Community寫作與編輯github.com

AngChow/dms-query

連接阿里雲 DMS (MySQL) 資料庫的通用操作 Codex 技能:查詢資料、查看表結構、多格式匯出、附安全護欄的寫入操作

dms-query 是什麼?

此技能為一個專為阿里雲 DMS (MySQL) 設計的資料庫操作工具,提供安全、高效且靈活的查詢與執行環境。它支援多種平台(如 Codex),透過內建的安全護欄強制預設唯讀,確保未經明確授權的寫入操作不會發生。主要功能包括:列出資料庫與資料表、查看表結構、執行 SQL 查詢、以及將結果匯出為 xlsx、csv、json 等格式。對於寫入操作(INSERT、UPDATE、DELETE、DDL),該技能實施嚴格的「預覽 → 展示影響 → 使用者確認 → 執行」四步驟流程,且每條寫入語句都需獨立確認,避免意外修改。此外,它支援從命令列參數、檔案或標準輸入讀取 SQL,並可透過 `--db` 參數臨時覆蓋預設資料庫。該技能會自動處理常見錯誤(如連線逾時、缺少依賴或環境變數),並提供清晰的引導提示,提升使用者體驗並降低操作風險。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add AngChow/dms-query

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

DMS 資料庫通用操作 Skill

連接阿里雲 DMS (MySQL) 查詢與執行資料庫資料,內建安全護欄。支援覆蓋預設庫、便捷命令、多格式匯出。

核心安全原則(強制)

  1. 預設唯讀:未加 --write 時僅執行 SELECT / SHOW / DESCRIBE / EXPLAIN / WITH / USE,腳本自動攔截一切寫入操作並退出。
  2. 寫入操作必須二次確認:即使用戶明確要求修改/刪除資料,也必須走「預覽 -> 展示影響 -> 用戶確認 -> 執行」四步驟流程,不得跳過。
  3. 不做超出用戶意圖的修改:用戶只要求「查」時絕不「改」;用戶要求「改 A」時絕不順帶「改 B」。
  4. 一次只做一件事:每條寫入操作獨立預覽、獨立確認,不批次執行多條未經逐一確認的寫入語句。

腳本

{SKILL_DIR} = ~/.codex/skills/dms-query/scripts。主腳本 dms_exec.py。

便捷命令

# 列出所有資料庫
python3 {SKILL_DIR}/dms_exec.py --databases

# 列出指定庫的資料表(不傳庫名則用 DMS_DB)
python3 {SKILL_DIR}/dms_exec.py --tables          # 用 DMS_DB 預設庫
python3 {SKILL_DIR}/dms_exec.py --tables shop   # 指定庫

# 查看資料表結構
python3 {SKILL_DIR}/dms_exec.py --describe mydb.users
python3 {SKILL_DIR}/dms_exec.py --db shop --describe products

讀取 SQL 的三種方式

# 1. 命令列直接傳
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT * FROM mydb.users LIMIT 5"

# 2. 從檔案讀取
python3 {SKILL_DIR}/dms_exec.py --file /path/to/query.sql

# 3. 從 stdin 讀取
echo "SHOW DATABASES" | python3 {SKILL_DIR}/dms_exec.py

覆蓋預設庫

預設連接 DMS_DB 環境變數指定的庫。用 --db 可臨時覆蓋,不影響其他終端:

python3 {SKILL_DIR}/dms_exec.py --db shop --sql "SELECT id, name FROM products LIMIT 10"
python3 {SKILL_DIR}/dms_exec.py --db mydb --tables

匯出結果

# 匯出 xlsx
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT ..." -o result.xlsx

# 匯出 csv
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT ..." -o result.csv

# 匯出 json(陣列物件格式)
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT ..." -o result.json

# TSV 原始輸出(適合管線處理,不匯出檔案)
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT ..." --raw

--display-rows N(預設 200)控制終端列印行數。匯出檔案時不受此限制。

查詢資料(唯讀)

# 查看所有資料庫
python3 {SKILL_DIR}/dms_exec.py --databases

# 查看某個庫的資料表
python3 {SKILL_DIR}/dms_exec.py --tables mydb

# 查看資料表結構
python3 {SKILL_DIR}/dms_exec.py --describe mydb.users

# 查詢資料
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT id, name, email FROM mydb.users LIMIT 10"

# 查看建立資料表語句
python3 {SKILL_DIR}/dms_exec.py --sql "SHOW CREATE TABLE mydb.users"

# 跨庫查詢(SQL 中用 db.table 全名即可,無需 --db)
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT c.name, COUNT(*) FROM mydb.users u LEFT JOIN shop.companies c ON u.company_id = c.id GROUP BY c.name"

查詢大量資料時,在 SQL 中加 LIMIT;如需全量匯出,用 -o file.xlsx。

執行時期錯誤處理

腳本已內建友好錯誤提示,執行失敗時根據輸出判斷原因並引導用戶:

錯誤特徵原因處理
Can't connect to MySQL server ... (timed out)VPN 未連接提醒用戶:「DMS 為內網地址,請先連接公司 VPN 後重試」
缺少 pymysql 模組依賴未安裝提示執行 pip3 install pymysql -i https://pypi.tuna.tsinghua.edu.cn/simple
缺少環境變數 DMS_*未配置連接參數提醒用戶在 ~/.zshenv 配置 DMS 環境變數後新開終端
拒絕執行寫入操作未加 --write正常攔截,按寫入操作確認流程處理

腳本輸出已包含排查建議,可直接轉述給用戶。無需自行猜測原因。

寫入操作確認流程(強制,不可跳過)

當用戶明確要求修改/刪除/建立資料時,必須按以下四步驟執行:

Step 1 - 產生預覽(dry-run)

python3 {SKILL_DIR}/dms_exec.py --sql "<寫入操作 SQL>" --write

腳本預設 dry-run:對 DML 用交易執行後 ROLLBACK 取得精確受影響行數,並 SELECT 預覽受影響行;對 INSERT 展示目標表、列、值;對 DDL 給出影響說明。不實際修改資料。

Step 2 - 向用戶展示影響範圍

基於預覽輸出,用中文向用戶清晰說明:

  • 操作類型:INSERT / UPDATE / DELETE / DDL(具體哪種)
  • 目標表:涉及的資料表名稱
  • 影響行數:多少行會被修改/刪除/插入
  • 具體變更:
    • UPDATE:哪些欄位從什麼值改成什麼值(展示預覽行)
    • DELETE:將刪除哪些行(展示預覽行)
    • INSERT:將插入什麼資料(展示資料列和值)
    • DDL:結構變更的具體內容
  • 是否可逆:DROP/TRUNCATE 不可逆,需特別強調
  • 無 WHERE 警告:若 UPDATE/DELETE 無 WHERE 子句,必須強調「將影響全表」

Step 3 - 等待用戶明確確認

用戶必須回覆肯定語意(「確認」/「執行」/「沒問題」等)。不得自行判斷「用戶應該是同意的」而跳過。 如果用戶猶豫或提出修改,回到 Step 1 重新預覽。

Step 4 - 執行

python3 {SKILL_DIR}/dms_exec.py --sql "<寫入操作 SQL>" --write --confirm

執行後報告受影響行數。

流程範例

用戶說:「把 users 表裡 feedback_type 為 2 的紀錄的 feedback 欄位更新為 '已處理'」

# Step 1: 預覽
python3 {SKILL_DIR}/dms_exec.py \
  --sql "UPDATE mydb.users SET feedback = '已處理' WHERE feedback_type = 2" \
  --write

# Step 2: 展示預覽結果給用戶(受影響行數、預覽行、不可逆性)
# Step 3: 等待用戶確認
# Step 4: 確認後執行
python3 {SKILL_DIR}/dms_exec.py \
  --sql "UPDATE mydb.users SET feedback = '已處理' WHERE feedback_type = 2" \
  --write --confirm

參數速查

參數說明
--sql "..."直接傳 SQL
--file / -f PATH從檔案讀取 SQL
--db NAME覆蓋預設庫名(DMS_DB)
--databases列出所有庫
--tables [DB]列出資料表(可選庫名)
--describe TABLE查看資料表結構
-o FILE匯出 xlsx/csv/json
--rawTSV 原始輸出
--display-rows N終端顯示行數(預設 200)
--timeout N連線逾時秒數(預設 15)
--write允許寫入操作
--confirm確認執行寫入操作(需配合 --write)

完成後

  • 查詢操作:報告行數與關鍵資料摘要(或匯出檔案路徑)。
  • 寫入操作:報告受影響行數及操作結果。

相關技能