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)
- Read-only by default: Without
--write, onlySELECT / SHOW / DESCRIBE / EXPLAIN / WITH / USEare executed. The script automatically blocks all write operations and exits. - 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.
- 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".
- 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
LIMITto 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 Pattern | Cause | Action |
|---|---|---|
Can't connect to MySQL server ... (timed out) | VPN not connected | Remind the user: "DMS is an internal network address. Please connect to the company VPN and retry." |
Missing pymysql module | Dependency not installed | Prompt: pip3 install pymysql -i https://pypi.tuna.tsinghua.edu.cn/simple |
Missing environment variable DMS_* | Connection parameters not configured | Remind the user to configure DMS environment variables in ~/.zshenv and open a new terminal |
Refusing to execute write operation | --write not provided | Normal 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
| Parameter | Description |
|---|---|
--sql "..." | Pass SQL directly |
--file / -f PATH | Read SQL from a file |
--db NAME | Override the default database name (DMS_DB) |
--databases | List all databases |
--tables [DB] | List tables (optional database name) |
--describe TABLE | View table structure |
-o FILE | Export to xlsx/csv/json |
--raw | TSV raw output |
--display-rows N | Number of rows to display in terminal (default 200) |
--timeout N | Connection timeout in seconds (default 15) |
--write | Allow write operations |
--confirm | Confirm 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.