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。
• 尝试通过 MCP 创建 MySQL 实例。工具已不再提供实例配置功能：新环境使用 PostgreSQL，实例只能在控制台中创建。
• 将文档数据库任务当作 MySQL 管理任务处理。
• 创建新 SQL 表后，未检查 _openid 和权限。
• 未经明确确认，或未检查环境是否仍需要该实例，就销毁 MySQL。
• 使用 getConnectionInfo（或推断主机 / 密码）为新应用构建默认 TCP 客户端。优先使用 SDK / runQuery / runStatement；TCP 凭据仅适用于明确的迁移例外情况。

何时使用此技能

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

• 检查或查询 SQL 数据
• 销毁现有 MySQL 实例
• 轮询正在执行的 MySQL 任务（创建任务在控制台中启动，MCP 不再创建实例）
• 修改数据或架构（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、执行写入 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 客户端。对于新业务的增删改查，请勿使用此操作；优先使用 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="destroyMySQL" 销毁 MySQL
  • 使用 action="runStatement" 执行 INSERT、UPDATE、DELETE、CREATE TABLE、ALTER TABLE、DROP TABLE
  • 使用 action="initializeSchema" 初始化表和索引

此处不提供实例创建功能。 provisionMySQL 已从操作集中移除：携带该操作的调用会导致模式验证失败；如果实例不存在，则会返回 MYSQL_NOT_CREATED 和控制台入口，而不是创建提示。

重要： 创建新表时，必须包含 _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. 如果不存在实例，停止。MCP 不再提供 MySQL 配置服务：结果为 MYSQL_NOT_CREATED，其中包含控制台入口，但不提供创建提示。
3. 新环境应使用 CloudBase PostgreSQL — 请参阅 ../postgresql-development-cloudbase/SKILL.md。
4. 仍可查看通过工具外部创建的实例：轮询 queryMysqlDatabase(action="describeCreateResult") 或 queryMysqlDatabase(action="describeTaskStatus")，只有在生命周期状态为 READY 后才能继续。
5. 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 skill。
  • 后端 Node 应用 -> Node Relational Database quickstart。

作为 MCP Agent 工作时，处理 CloudBase Relational Database 应始终优先使用这些 MCP 工具，并避免在同一工作流中混用 SDK 初始化。