CommunityWriting & Editinggithub.com

AngChow/dms-query

Connect to Alibaba Cloud DMS (MySQL) database with a general-purpose Codex Skill: query data, view table structures, export in multiple formats, and perform write operations with safety guards.

What is dms-query?

This skill provides a secure interface for interacting with Alibaba Cloud Database Management Service (DMS) for MySQL databases from within AI agent environments like Codex. It supports read-only operations (SELECT, SHOW, DESCRIBE, EXPLAIN, WITH, USE) by default, enforcing strict safety guards that block all write operations unless the `--write` flag is explicitly provided. For write operations (INSERT, UPDATE, DELETE, DDL), it mandates a mandatory four-step confirmation process: generate a dry-run preview, display the impact (including affected rows, changed values, and irreversibility warnings), wait for explicit user confirmation, and only then execute. Key features include listing databases/tables, describing table structures, querying data, and exporting results in XLSX, CSV, JSON, or raw TSV format. The skill also supports overriding the default database with `--db` and reading SQL from command line arguments, files, or stdin, making it flexible for various workflows. It includes built-in error handling for common issues like network timeouts, missing dependencies, and misconfigured environment variables, providing actionable guidance to users.

Works with~Claude Code✓Codex CLI~Cursor
npx skills add AngChow/dms-query

Installed? Explore more Writing & Editing skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

DMS Database General Operations Skill

Connect to Alibaba Cloud DMS (MySQL) to query and execute database operations, with built-in safety guards. Supports overriding the default database, convenient commands, and multi-format export.

Core Safety Principles (Mandatory)

  1. Read-only by default: Without --write, only SELECT / SHOW / DESCRIBE / EXPLAIN / WITH / USE are executed. The script automatically blocks all write operations and exits.
  2. Write operations require a second confirmation: Even if the user explicitly requests data modification/deletion, the four-step process (Preview -> Show Impact -> User Confirmation -> Execute) must be followed. Skipping is not allowed.
  3. Do not exceed the user's intent: If the user only asks to "query", never "modify"; if the user asks to "modify A", do not also "modify B".
  4. One thing at a time: Each write operation must be previewed and confirmed independently. Do not batch execute multiple write statements without individual confirmation.

Script

{SKILL_DIR} = ~/.codex/skills/dms-query/scripts. The main script is dms_exec.py.

Convenient Commands

# List all databases
python3 {SKILL_DIR}/dms_exec.py --databases

# List tables in the specified database (uses DMS_DB if not provided)
python3 {SKILL_DIR}/dms_exec.py --tables          # Uses the default DMS_DB database
python3 {SKILL_DIR}/dms_exec.py --tables shop   # Specified database

# View table structure
python3 {SKILL_DIR}/dms_exec.py --describe mydb.users
python3 {SKILL_DIR}/dms_exec.py --db shop --describe products

Three Ways to Read SQL

# 1. Directly from the command line
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT * FROM mydb.users LIMIT 5"

# 2. From a file
python3 {SKILL_DIR}/dms_exec.py --file /path/to/query.sql

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

Override the Default Database

The default connection uses the database specified in the DMS_DB environment variable. Use --db to temporarily override it without affecting other terminals:

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

Export Results

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

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

# Export to json (array of objects format)
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT ..." -o result.json

# TSV raw output (suitable for piping, no file export)
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT ..." --raw

--display-rows N (default 200) controls the number of rows printed to the terminal. This limit does not apply when exporting to a file.

Querying Data (Read-Only)

# View all databases
python3 {SKILL_DIR}/dms_exec.py --databases

# View tables in a database
python3 {SKILL_DIR}/dms_exec.py --tables mydb

# View table structure
python3 {SKILL_DIR}/dms_exec.py --describe mydb.users

# Query data
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT id, name, email FROM mydb.users LIMIT 10"

# View table creation statement
python3 {SKILL_DIR}/dms_exec.py --sql "SHOW CREATE TABLE mydb.users"

# Cross-database query (use full db.table name in SQL, no need for --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"

When querying large amounts of data, add LIMIT to the SQL. For a full export, use -o file.xlsx.

Runtime Error Handling

The script includes built-in friendly error messages. When execution fails, determine the cause based on the output and guide the user:

Error PatternCauseAction
Can't connect to MySQL server ... (timed out)VPN not connectedRemind the user: "DMS is an internal network address. Please connect to the company VPN and retry."
Missing pymysql moduleDependency not installedPrompt: pip3 install pymysql -i https://pypi.tuna.tsinghua.edu.cn/simple
Missing environment variable DMS_*Connection parameters not configuredRemind the user to configure DMS environment variables in ~/.zshenv and open a new terminal
Refusing to execute write operation--write not providedNormal interception; follow the write operation confirmation process

The script output already includes troubleshooting suggestions. You can directly relay them to the user. Do not guess the cause on your own.

Write Operation Confirmation Process (Mandatory, Cannot Be Skipped)

When the user explicitly requests data modification/deletion/creation, the following four steps must be followed:

Step 1 - Generate a Preview (Dry-Run)

python3 {SKILL_DIR}/dms_exec.py --sql "<Write SQL>" --write

By default, the script performs a dry-run: for DML, it executes the transaction and then ROLLBACK to get the exact number of affected rows, plus SELECT previews the affected rows; for INSERT, it shows the target table, columns, and values; for DDL, it provides an impact description. The data is NOT actually modified.

Step 2 - Show the Impact to the User

Based on the preview output, clearly explain to the user in Chinese:

  • Operation type: INSERT / UPDATE / DELETE / DDL (specifically which)
  • Target table: The table(s) involved
  • Affected rows: How many rows will be modified/deleted/inserted
  • Specific changes:
    • UPDATE: Which fields changed from what value to what value (show preview rows)
    • DELETE: Which rows will be deleted (show preview rows)
    • INSERT: What data will be inserted (show columns and values)
    • DDL: The specific structural change
  • Reversibility: DROP/TRUNCATE is irreversible and must be emphasized
  • No WHERE clause warning: If UPDATE/DELETE lacks a WHERE clause, emphasize that it will affect the entire table

Step 3 - Wait for Explicit User Confirmation

The user must reply with an affirmative statement ("Confirm" / "Execute" / "No problem" etc.). Do not assume the user agrees and skip this step. If the user hesitates or requests changes, return to Step 1 for a new preview.

Step 4 - Execute

python3 {SKILL_DIR}/dms_exec.py --sql "<Write SQL>" --write --confirm

Report the number of affected rows after execution.

Process Example

The user says: "Update the feedback field of records with feedback_type of 2 in the users table to 'Processed'"

# Step 1: Preview
python3 {SKILL_DIR}/dms_exec.py \
  --sql "UPDATE mydb.users SET feedback = 'Processed' WHERE feedback_type = 2" \
  --write

# Step 2: Show preview results to the user (affected rows, preview rows, irreversibility)
# Step 3: Wait for user confirmation
# Step 4: Execute after confirmation
python3 {SKILL_DIR}/dms_exec.py \
  --sql "UPDATE mydb.users SET feedback = 'Processed' WHERE feedback_type = 2" \
  --write --confirm

Parameter Quick Reference

ParameterDescription
--sql "..."Pass SQL directly
--file / -f PATHRead SQL from a file
--db NAMEOverride the default database name (DMS_DB)
--databasesList all databases
--tables [DB]List tables (optional database name)
--describe TABLEView table structure
-o FILEExport to xlsx/csv/json
--rawTSV raw output
--display-rows NNumber of rows to display in terminal (default 200)
--timeout NConnection timeout in seconds (default 15)
--writeAllow write operations
--confirmConfirm execution of write operations (requires --write)

Upon Completion

  • Query operation: Report the number of rows and a summary of key data (or the export file path).
  • Write operation: Report the number of affected rows and the operation result.

Related Skills