alibabacloud-dms-skill

Alibaba Cloud DMS 数据库读写

通过 Alibaba Cloud DMS OpenAPI 搜索目标数据库，并执行 SQL 查询和数据修改。

场景说明

此技能实现以下工作流：

1. 搜索目标数据库 — 按关键字搜索数据库，以获取 Database ID
2. 执行 SQL 查询 — 在目标数据库上执行 SQL 语句

架构

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

前提条件

AI-Mode 生命周期（必须按顺序执行）

此技能必须在 AI-Mode 会话中运行。请将以下五个步骤视为严格的生命周期——不得跳过、调换顺序，也不得将设置步骤与命令执行交叉进行：

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)

步骤 1–3 属于设置（本节）。步骤 4 见核心工作流。步骤 5 见清理。

预检查

预检查 0：需要 Aliyun CLI >= 3.3.3 运行 aliyun version，确认版本 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装或更新， 或参阅 references/cli-installation-guide.md 查看安装说明。

预检查 1：启用 AI-Mode [必须] 在执行任何其他配置或命令之前，运行 aliyun configure ai-mode enable 启用 AI-Mode。 这将激活 AI-Mode 会话，下游 OpenAPI 服务会借此识别由 Agent 发起的流量。

预检查 2：在 AI-Mode 下注册技能 User-Agent [必须] 运行 aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-dms-skill 将此技能的标识注册为当前会话的 AI-Mode User-Agent。 请在 ai-mode enable 后立即运行此命令，并在任何插件更新或 DMS 命令之前完成注册。

预检查 3：需要更新 Aliyun CLI 插件 [必须] 运行 aliyun configure set --auto-plugin-install true，启用自动安装插件。 [必须] 运行 aliyun plugin update，确保所有现有插件始终为最新版本。 必须在启用 AI-Mode 并注册 User-Agent 之后更新插件，这样插件管理器本身才能报告正确的标识。

• Aliyun CLI >= 3.3.3
• jq（用于解析 JSON）：brew install jq
• 通过 aliyun configure 配置凭据

预检查 4：需要 Alibaba Cloud 凭据

安全规则：

• 绝不读取、回显或打印 AK/SK 值（例如，禁止使用 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
• 绝不要求用户直接在对话或命令行中输入 AK/SK
• 绝不使用包含明文凭据值的 aliyun configure set
• 仅使用 aliyun configure list 检查凭据状态

aliyun configure list

检查输出中是否存在有效配置（AK、STS 或 OAuth 身份）。

如果不存在有效配置，请在此处停止。

1. 从 Alibaba Cloud 控制台获取凭据
2. 在此会话之外配置凭据（在终端中运行 aliyun configure，或在 Shell 配置文件中设置环境变量）
3. 返回并重新运行，直到 aliyun configure list 显示有效配置

[必须] 每条命令的 CLI User-Agent — 除预检查 2 中注册的 AI-Mode User-Agent 外， 步骤 4 中每次调用 aliyun CLI 命令时也必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dms-skill 每条命令的标志与 AI-Mode 会话级设置相辅相成——两者都必须提供，这样即使 AI-Mode 会话过期，也能确保每个请求都发送此标识。

RAM 权限

[必须] RAM 权限预检查： 执行前请确认当前用户具有以下 RAM 权限。 完整权限列表请参阅 references/ram-policies.md。

参数确认

重要：参数确认 — 执行任何命令或 API 调用之前， 必须与用户确认所有可由用户自定义的参数（例如，数据库关键词、SQL 语句、db-id 等）。 未经用户明确批准，不得假设或使用默认值。

参数	必填/可选	描述	默认值
keyword	必填	数据库搜索关键词（1-128 个字符，仅限字母数字）	-
db-id	必填	数据库 ID（正整数，通过搜索获取）	-
sql	必填	要执行的 SQL 语句（1-10000 个字符）	-
logic	可选	是否使用逻辑数据库模式	false
force	可选	确认写入操作（INSERT/UPDATE/DELETE）	false
dry-run	可选	预览写入操作但不执行	false

核心工作流

任务 1：搜索目标数据库

按关键词搜索数据库以获取数据库 ID：

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

示例：

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

输出包含 database_id、schema_name、db_type、host、port 等信息。

任务 2：执行 SQL 查询

使用上一步获取的数据库 ID 执行 SQL：

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

写入操作保护

对于写入操作（INSERT/UPDATE/DELETE），脚本会执行保护性预检查：

参数	描述
--force	必须使用此参数确认并执行写入操作
--dry-run	预览写入操作但不执行

DDL 操作（DROP/TRUNCATE/ALTER/RENAME）会被完全阻止 — 必须通过 DMS 控制台执行。

示例：

# 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

完整示例

# 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"

成功验证

执行 SQL 后，检查返回结果：

1. 脚本返回码为 0
2. 输出包含查询结果（列名和行数据）
3. 没有错误消息

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

清理

此技能会执行读写操作，但不会创建持久化资源，因此无需释放数据库资源。

但是，AI-Mode 生命周期要求执行明确的 teardown 步骤：

[MUST] 所有任务完成后禁用 AI-Mode 在此技能会话中的所有 DMS 命令执行完毕后（无论成功或失败），运行 aliyun configure ai-mode disable 这会终止 AI-Mode 会话，并防止已注册的 AlibabaCloud-Agent-Skills/alibabacloud-dms-skill User-Agent 泄漏到之后无关的 CLI 使用中。

aliyun configure ai-mode disable

写入操作安全

操作类型	行为
SELECT / SHOW / DESC	直接执行
INSERT / UPDATE / DELETE	需要 --force 或 --dry-run
DROP / TRUNCATE / ALTER / RENAME	已阻止 — 请使用 DMS 控制台

可用脚本

脚本	描述
scripts/search_database.sh	按关键词搜索数据库
scripts/execute_query.sh	执行 SQL 查询

注意： 脚本使用通过 aliyun configure 配置的 aliyun-cli 凭据。

最佳实践

1. 确认数据库 — 执行 SQL 前，验证目标数据库
2. 使用 --json 参数 — 便于以编程方式处理输出
3. 预览写入操作 — 对 INSERT/UPDATE/DELETE，务必先使用 --dry-run
4. 明确确认 — 仅在检查预览后使用 --force
5. 避免 DDL 操作 — DROP/TRUNCATE/ALTER/RENAME 会被阻止；请改用 DMS 控制台

参考链接

文档	描述
references/cli-installation-guide.md	CLI 安装指南
references/ram-policies.md	RAM 权限策略
references/related-apis.md	相关 API 列表
references/acceptance-criteria.md	验收标准