阿里云 DMS 数据库读写

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

场景说明

此 skill 实现以下工作流：

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

架构

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

前提条件

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

此 skill 必须在 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 参见[核心工作流](#core-workflow)。步骤 5 参见[清理](#cleanup)。

预检查

预检查 0：要求阿里云 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 下注册 skill 的 User-Agent

[必须] 运行 aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-dms-skill

将此 skill 的标识符注册为当前会话的 AI-Mode User-Agent。

在 ai-mode enable 之后立即运行此命令，并确保在进行任何插件更新或执行 DMS 命令之前运行。

预检查 3：必须更新阿里云 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：必须具备阿里云凭证

安全规则：

- 禁止读取、回显或打印 AK/SK 值（例如，严禁使用 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）

- 禁止要求用户直接在对话或命令行中输入 AK/SK

- 禁止在 aliyun configure set 中使用字面量凭证值

- 只能使用 aliyun configure list 检查凭证状态

```bash

aliyun configure list

```

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

如果不存在有效的配置文件，在此处停止。

1. 从阿里云控制台获取凭证

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, ...}]

清理

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

但是，AI-Mode 生命周期要求执行显式清理步骤：

[必须] 所有任务完成后停用 AI-Mode

此 skill 会话中的所有 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](references/cli-installation-guide.md) | CLI 安装指南 | | [references/ram-policies.md](references/ram-policies.md) | RAM 权限策略 | | [references/related-apis.md](references/related-apis.md) | 相关 API 列表 | | [references/acceptance-criteria.md](references/acceptance-criteria.md) | 验收标准 |