Alibaba Cloud DMS Database Read/Write#

Search for target databases and execute SQL queries and data modifications via Alibaba Cloud DMS OpenAPI.

Scenario Description#

This skill implements the following workflow:

1. Search Target Database — Search databases by keyword to get Database ID
2. Execute SQL Query — Execute SQL statements on the target database

Architecture#

text

User Request → Search Database → Get Database ID → Execute SQL → Return Results

Prerequisites#

AI-Mode Lifecycle (MUST follow in order)#

This skill MUST run inside an AI-Mode session. Treat the following five steps as a strict lifecycle — do not skip, reorder, or interleave the setup steps with command execution:

text

1. aliyun configure ai-mode enable                                              # Enable AI-Mode
2. aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-dms-skill   # Register skill User-Agent
3. aliyun configure set --auto-plugin-install true && aliyun plugin update      # Plugin update
4. <execute DMS commands via ./scripts/*.sh>                                    # Execute commands
5. aliyun configure ai-mode disable                                             # Disable AI-Mode (Cleanup)

Steps 1–3 belong to setup (this section). Step 4 is covered by Core Workflow. Step 5 is covered by Cleanup.

Pre-checks#

Pre-check 0: Aliyun CLI >= 3.3.3 required Run aliyun version to verify >= 3.3.3. If not installed or version too low, run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install/update, or see references/cli-installation-guide.md for installation instructions.

Pre-check 1: Enable AI-Mode [MUST] run aliyun configure ai-mode enable to enable AI-Mode before any other configuration or command. This activates the AI-Mode session that downstream OpenAPI services use to recognize agent-issued traffic.

Pre-check 2: Register skill User-Agent under AI-Mode [MUST] run aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-dms-skill to register this skill's identifier as the AI-Mode User-Agent for the current session. Run this immediately after ai-mode enable and before any plugin update or DMS command.

Pre-check 3: Aliyun CLI plugin update required [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation. [MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date. Plugin update MUST happen AFTER AI-Mode is enabled and the User-Agent is registered, so the plugin manager itself reports the correct identifier.

• Aliyun CLI >= 3.3.3
• jq (for JSON parsing): brew install jq
• Credentials configured via aliyun configure

Pre-check 4: Alibaba Cloud Credentials Required

Security Rules:

• NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)
• NEVER ask the user to input AK/SK directly in the conversation or command line
• NEVER use aliyun configure set with literal credential values
• ONLY use aliyun configure list to check credential status

bash

aliyun configure list

Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console
2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
3. Return and re-run after aliyun configure list shows a valid profile

[MUST] Per-command CLI User-Agent — In addition to the AI-Mode User-Agent registered in Pre-check 2, every aliyun CLI command invocation in step 4 MUST also include: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dms-skill The per-command flag and the AI-Mode session-level setting are complementary — both MUST be present so the identifier is sent on every request even if the AI-Mode session expires.

RAM Permissions#

[MUST] RAM Permission Pre-check: Verify that the current user has the following RAM permissions before execution. See references/ram-policies.md for the complete permission list.

Parameter Confirmation#

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., database keyword, SQL statement, db-id, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

ParameterRequired/OptionalDescriptionDefaultkeywordRequiredDatabase search keyword (1-128 chars, alphanumeric)-db-idRequiredDatabase ID (positive integer, obtained from search)-sqlRequiredSQL statement to execute (1-10000 chars)-logicOptionalWhether to use logic database modefalseforceOptionalConfirm write operations (INSERT/UPDATE/DELETE)falsedry-runOptionalPreview write operations without executingfalse

Core Workflow#

Task 1: Search Target Database#

Search for databases by keyword to get the Database ID:

bash

./scripts/search_database.sh <keyword> --json

Example:

bash

# Search for databases containing "mydb"
./scripts/search_database.sh mydb --json

The output includes database_id, schema_name, db_type, host, port, etc.

Task 2: Execute SQL Query#

Execute SQL using the Database ID obtained in the previous step:

bash

./scripts/execute_query.sh --db-id <database_id> --sql "<SQL_statement>"

Write Operation Protection

For write operations (INSERT/UPDATE/DELETE), the script implements protective pre-check:

ParameterDescription--forceRequired to confirm and execute write operations--dry-runPreview write operations without executing

DDL Operations (DROP/TRUNCATE/ALTER/RENAME) are completely blocked — these must be executed via DMS Console.

Examples:

bash

# Read operations (no confirmation needed)
./scripts/execute_query.sh --db-id 78059000 --sql "SHOW TABLES"
./scripts/execute_query.sh --db-id 78059000 --sql "SELECT * FROM users LIMIT 10" --json

# Write operations - preview first (recommended)
./scripts/execute_query.sh --db-id 78059000 --sql "INSERT INTO users (name) VALUES ('test')" --dry-run

# Write operations - execute with confirmation
./scripts/execute_query.sh --db-id 78059000 --sql "INSERT INTO users (name) VALUES ('test')" --force
./scripts/execute_query.sh --db-id 78059000 --sql "UPDATE users SET name='test' WHERE id=1" --force
./scripts/execute_query.sh --db-id 78059000 --sql "DELETE FROM users WHERE id=1" --force

# Logic database mode
./scripts/execute_query.sh --db-id 78059000 --sql "SELECT 1" --logic

Complete Example#

bash

# 1. Search database (assuming searching for "order")
./scripts/search_database.sh order --json
# Example output:
# [{"DatabaseId": "78059000", "SchemaName": "order_db", ...}]

# 2. Execute query
./scripts/execute_query.sh --db-id 78059000 --sql "SELECT COUNT(*) FROM orders"

Success Verification#

After executing SQL, check the returned results:

1. Script return code is 0
2. Output contains query results (column names and row data)
3. No error messages

bash

# Verify query success
./scripts/execute_query.sh --db-id <db-id> --sql "SELECT 1" --json
# Expected output: [{"Success": true, "RowCount": 1, ...}]

Cleanup#

This skill performs read and write operations but does not create persistent resources, so no database resources need to be released.

However, the AI-Mode lifecycle requires an explicit teardown step:

[MUST] Disable AI-Mode after all tasks complete Run aliyun configure ai-mode disable once all DMS commands in this skill session have finished (success or failure). This terminates the AI-Mode session and prevents the registered AlibabaCloud-Agent-Skills/alibabacloud-dms-skill User-Agent from leaking into subsequent unrelated CLI usage.

bash

aliyun configure ai-mode disable

Write Operation Safety#

Operation TypeBehaviorSELECT / SHOW / DESCExecute directlyINSERT / UPDATE / DELETERequire --force or --dry-runDROP / TRUNCATE / ALTER / RENAMEBlocked — use DMS Console

Available Scripts#

ScriptDescriptionscripts/search_database.shSearch databases by keywordscripts/execute_query.shExecute SQL queries

Note: Scripts use aliyun-cli credentials configured via aliyun configure.

Best Practices#

1. Confirm database — Verify the target database before executing SQL
2. Use --json parameter — Facilitates programmatic processing of output
3. Preview write operations — Always use --dry-run first for INSERT/UPDATE/DELETE
4. Explicit confirmation — Use --force only after reviewing the preview
5. Avoid DDL operations — DROP/TRUNCATE/ALTER/RENAME are blocked; use DMS Console instead

Reference Links#

DocumentDescriptionreferences/cli-installation-guide.mdCLI Installation Guidereferences/ram-policies.mdRAM Permission Policiesreferences/related-apis.mdRelated API Listreferences/acceptance-criteria.mdAcceptance Criteria