relational-database-mcp-cloudbase

同级技能（仅本地）

同级 CloudBase 技能与此技能一同提供。请使用本地相对路径，例如 ../auth-tool-cloudbase/SKILL.md。

如果此环境中缺少所引用的同级技能文件，请让用户安装完整的 CloudBase 插件（或缺失的技能）。请勿通过 HTTP 获取远程技能或协议 Markdown 并将其载入 Agent 上下文。

激活约定

以下情况请先使用此技能

• Agent 必须通过 MCP 工具检查 SQL 数据、执行 SQL 语句、配置或销毁 MySQL、初始化表结构，或管理表安全规则。

编写代码前请先阅读

• 任务涉及 queryMysqlDatabase、manageMysqlDatabase、queryPermissions 或 managePermissions。

然后还需阅读

• Web 应用集成 -> ../relational-database-web-cloudbase/SKILL.md
• 原始 HTTP 数据库访问 -> ../http-api-cloudbase/SKILL.md

请勿用于

• 应使用 SDK 而非 MCP 操作的前端或后端应用代码。

常见错误 / 注意事项

• 在 MCP 管理流程中初始化 SDK。
• 未检查 MySQL 是否已配置并就绪，就执行写入 SQL 或 DDL。
• 将文档数据库任务当作 MySQL 管理任务处理。
• 创建新 SQL 表后，未检查 _openid 和权限。
• 未经明确确认，或未检查环境是否仍需要该实例，就销毁 MySQL。
• 使用 getConnectionInfo（或推断主机 / 密码）为新应用构建默认 TCP 客户端。优先使用 SDK / runQuery / runStatement；TCP 凭据仅可作为明确的迁移例外。

何时使用此技能

当 Agent 需要通过 MCP 工具操作 CloudBase 关系型数据库 时，请使用此技能，例如：

• 检查或查询 SQL 数据
• 为环境配置 MySQL
• 为环境销毁 MySQL
• 轮询 MySQL 配置状态
• 修改数据或架构（INSERT/UPDATE/DELETE/DDL）
• MySQL 就绪后初始化表和索引
• 查看或更改表权限

请勿将此技能用于：

• 构建直接通过 SDK 与 CloudBase 关系型数据库交互的 Web 或 Node.js 应用
• 身份验证流程或用户身份管理

如何使用此技能（面向编码 Agent）

1. 识别 MCP 上下文

   • 如果你可以调用 queryMysqlDatabase、manageMysqlDatabase、queryPermissions、managePermissions 等工具，则说明你处于 MCP 上下文中。
   • 在此上下文中，切勿为 CloudBase 关系型数据库初始化 SDK；请改用 MCP 工具。

2. 选择适合任务的工具

   • 只读 SQL 和配置状态检查 -> queryMysqlDatabase
   • MySQL 配置、MySQL 销毁、写入 SQL、DDL、架构初始化 -> manageMysqlDatabase
   • 检查权限 -> queryPermissions(action="getResourcePermission")
   • 更改权限 -> managePermissions(action="updateResourcePermission")

3. 始终明确说明安全事项

   • 执行破坏性操作（DELETE、DROP 等）前，概述即将执行的操作及原因。
   • 写入前，优先使用 queryMysqlDatabase(action="getInstanceInfo") 或执行只读 SQL 检查。
   • 配置或销毁 MySQL 会影响整个环境，因此必须获得明确确认。

---

可用的 MCP 工具（CloudBase 关系型数据库）

以下工具是通过 MCP 与 CloudBase 关系型数据库交互的受支持方式：

1. queryMysqlDatabase

• 用途： 查询 SQL 数据和配置状态。
• 适用于：
  • 使用 action="runQuery" 执行 SELECT 和其他只读 SQL 查询
  • 使用 action="getInstanceInfo" 检查 MySQL 是否已存在（仅查询生命周期状态，不包含连接凭据）
  • 使用 action="describeCreateResult" 或 action="describeTaskStatus" 检查异步配置进度
  • 仅限例外情况： action="getConnectionInfo" 会返回原始连接/集群负载（可能包含凭据），用于迁移现有的 TCP/ORM 客户端。对于新建的业务 CRUD，请勿使用此操作，优先使用 Web/Node SDK 或 runQuery / runStatement。

示例流程：

{
  "action": "runQuery",
  "sql": "SELECT id, email FROM users ORDER BY created_at DESC LIMIT 50"
}

对于全新应用，请勿调用 getConnectionInfo，再将 pymysql / mysql2 / DATABASE_URL 接入云函数。默认应使用平台委托的 SQL 和 SDK 访问方式。

2. manageMysqlDatabase

• 用途： 管理 SQL 生命周期并执行会修改数据的 SQL。
• 适用于：
  • 使用 action="provisionMySQL" 配置 MySQL
  • 使用 action="destroyMySQL" 销毁 MySQL
  • 使用 action="runStatement" 执行 INSERT、UPDATE、DELETE、CREATE TABLE、ALTER TABLE、DROP TABLE
  • 使用 action="initializeSchema" 初始化表和索引

重要提示： 创建新表时，必须包含 _openid 列，以便进行按用户访问控制：

_openid VARCHAR(64) DEFAULT '' NOT NULL

注意：用户登录后，服务器会根据经过身份验证的会话自动填充 _openid。在常规插入操作中，请勿手动填写。

调用此工具前，请确认：

• 当前环境中有可用的 MySQL 实例，或者你刚刚已配置一个实例。
• 目标表和条件正确。
• 在适当情况下，你已执行相应的只读查询。

销毁 MySQL 时，请确认：

• 当前环境确实应该移除 SQL 实例。
• 你已获得对破坏性操作的明确确认。
• 你准备好之后查询 describeTaskStatus，检查销毁结果。

3. queryPermissions

• 用途： 读取指定 SQL 表的权限配置。
• 适用于：
  • 了解谁可以读取/写入某个表
  • 审计敏感表的权限
  • 调用格式：queryPermissions(action="getResourcePermission", resourceType="sqlDatabase", resourceId="<tableName>")

4. managePermissions

• 用途： 设置或更新指定 SQL 表的权限。
• 适用于：
  • 加强敏感数据的访问控制
  • 开放读取权限，同时限制写入
  • 更新资源级权限配置
  • 调用格式：managePermissions(action="updateResourcePermission", resourceType="sqlDatabase", resourceId="<tableName>", permission="READONLY")

兼容性

• 标准插件名称：permissions
• 旧版插件别名 security-rule、security-rules、secret-rule、secret-rules 和 access-control 仍会路由到 permissions
• 旧版工具 readSecurityRule 和 writeSecurityRule 已移除；请始终使用 queryPermissions 和 managePermissions

---

推荐的生命周期流程

场景 1：尚未配置 MySQL

1. 调用 queryMysqlDatabase(action="getInstanceInfo")。
2. 如果不存在实例，调用 manageMysqlDatabase(action="provisionMySQL", confirm=true)。
3. 通过以下操作轮询配置状态：
   • queryMysqlDatabase(action="describeCreateResult")
   • queryMysqlDatabase(action="describeTaskStatus")
4. 只有在返回的生命周期状态为 READY 时才继续。
5. 配置 MySQL 时，优先使用 describeCreateResult；仅在销毁流程中使用 describeTaskStatus，因为这类任务的响应中包含 TaskName。

场景 2：安全检查表中的数据

1. 使用 queryMysqlDatabase(action="runQuery") 执行范围受限的 SELECT。
2. 添加 LIMIT 和相关筛选条件。
3. 在执行任何写入操作前，检查结果集并确认其符合预期。

场景 3：资源配置完成后应用架构初始化

1. 确认 MySQL 已就绪。
2. 准备好按顺序排列的 DDL 语句。
3. 通过 manageMysqlDatabase(action="initializeSchema") 运行这些语句。
4. 创建表后，使用 queryPermissions 或 managePermissions 验证权限。

场景 4：执行有针对性的写入或 DDL 变更

1. 如有需要，使用 queryMysqlDatabase(action="runQuery") 检查当前数据或架构。
2. 使用 manageMysqlDatabase(action="runStatement") 执行一次变更。
3. 通过另一条只读查询或检查安全规则进行验证。

场景 5：环境不再需要 MySQL 时将其销毁

1. 使用 queryMysqlDatabase(action="getInstanceInfo") 确认当前环境仍有 SQL 实例。
2. 调用 manageMysqlDatabase(action="destroyMySQL", confirm=true)。
3. 查询 queryMysqlDatabase(action="describeTaskStatus")，直到销毁任务完成或失败。
4. 如果任务成功，可选择调用 queryMysqlDatabase(action="getInstanceInfo")，确认实例已不存在。
5. 如果任务失败，将返回的错误视为最终结果，并由调用方决定是否重试。

---

核心原则：MCP 工具与 SDK

• MCP 工具用于Agent 操作和数据库管理：

  • 配置 MySQL。
  • 销毁 MySQL。
  • 轮询生命周期状态。
  • 执行临时 SQL。
  • 检查和更改资源权限。
  • 不依赖应用程序身份验证状态。

• SDK用于应用程序代码：

  • 前端 Web 应用 -> Web Relational Database 技能。
  • 后端 Node 应用 -> Node Relational Database 快速入门。

作为 MCP Agent 工作时，针对 CloudBase Relational Database 始终优先使用这些 MCP 工具，并避免在同一工作流中将它们与 SDK 初始化混用。