relational-database-mcp-cloudbase

## Sibling skills (local only) Sibling CloudBase skills ship beside this skill. Use local relative paths such as `../auth-tool-cloudbase/SKILL.md`. If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do **not** HTTP-fetch remote skill or protocol markdown into the agent context. ## Activation Contract ### Use this first when - The environment **already has** a CloudBase MySQL instance, and the agent must inspect that instance, run SQL, change schema, manage table security rules, or destroy it through MCP. - Do **not** choose this skill for a new relational database. New relational work uses `postgresql-development-cloudbase`. ### Read before writing code if - The task includes `queryMysqlDatabase`, `manageMysqlDatabase`, `queryPermissions`, or `managePermissions`. ### Then also read - Web application integration -> `../relational-database-web-cloudbase/SKILL.md` - Raw HTTP database access -> `../http-api-cloudbase/SKILL.md` ### Do NOT use for - Frontend or backend application code that should use SDKs instead of MCP operations. ### Common mistakes / gotchas - Initializing SDKs in an MCP management flow. - Running write SQL or DDL before confirming the environment already has a ready MySQL instance. - Trying to create a MySQL instance through MCP. Provisioning has been retired from the tool surface: new environments use PostgreSQL, and instances are only created in the console. - Treating document database tasks as MySQL management tasks. - Skipping `_openid` and permissions review after creating new SQL tables. - Destroying MySQL without explicit confirmation or without checking whether the environment still needs the instance. - Using `getConnectionInfo` (or inferred host/password) to build a default TCP client for new apps. Prefer SDK / `runQuery` / `runStatement`; TCP credentials are an explicit migration exception only. ## When to use this skill Use this skill when an **agent** needs to operate on **CloudBase Relational Database via MCP tools**, for example: - Inspecting or querying SQL data - Destroying an existing MySQL instance - Polling an in-flight MySQL task (create tasks are started in the console — MCP no longer creates instances) - Modifying data or schema (INSERT/UPDATE/DELETE/DDL) - Initializing tables and indexes after MySQL is ready - Reading or changing table permissions Do **NOT** use this skill for: - Building Web or Node.js applications that talk to CloudBase Relational Database directly through SDKs - Auth flows or user identity management ## How to use this skill (for a coding agent) 1. **Recognize MCP context** - If you can call tools like `queryMysqlDatabase`, `manageMysqlDatabase`, `queryPermissions`, `managePermissions`, you are in MCP context. - In this context, **never initialize SDKs for CloudBase Relational Database**; use MCP tools instead. 2. **Pick the right tool for the job** - Read-only SQL and create/destroy task status checks -> `queryMysqlDatabase` - MySQL destruction, write SQL, DDL, schema initialization -> `manageMysqlDatabase` - Inspect permissions -> `queryPermissions(action="getResourcePermission")` - Change permissions -> `managePermissions(action="updateResourcePermission")` 3. **Always be explicit about safety** - Before destructive operations (DELETE, DROP, etc.), summarize what you are about to run and why. - Prefer `queryMysqlDatabase(action="getInstanceInfo")` or a read-only SQL check before writes. - Destroying MySQL requires explicit confirmation because it has environment-level impact; provisioning is not offered here at all. --- ## Available MCP tools (CloudBase Relational Database) These tools are the supported way to interact with CloudBase Relational Database via MCP: ### 1. `queryMysqlDatabase` - **Purpose:** Query SQL data and instance / task state. - **Use for:** - Running `SELECT` and other read-only SQL queries with `action="runQuery"` - Checking whether MySQL already exists with `action="getInstanceInfo"` (lifecycle only — no connection credentials) - Inspecting an in-flight create or destroy task with `action="describeCreateResult"` or `action="describeTaskStatus"` (create tasks originate in the console) - **Exception only:** `action="getConnectionInfo"` returns the raw connection/cluster payload (may include credentials) for migrating existing TCP/ORM clients. Do **not** use this for new business CRUD — prefer Web/Node SDK or `runQuery` / `runStatement`. **Example flow:** ```json { "action": "runQuery", "sql": "SELECT id, email FROM users ORDER BY created_at DESC LIMIT 50" } ``` **Do NOT** call `getConnectionInfo` and then wire `pymysql` / `mysql2` / `DATABASE_URL` into a cloud function for greenfield apps. Platform-delegated SQL and SDK access are the default. ### 2. `manageMysqlDatabase` - **Purpose:** Manage an existing SQL instance and execute mutating SQL. - **Use for:** - Destroying MySQL with `action="destroyMySQL"` - Executing `INSERT`, `UPDATE`, `DELETE`, `CREATE TABLE`, `ALTER TABLE`, `DROP TABLE` with `action="runStatement"` - Initializing tables and indexes with `action="initializeSchema"` **Provisioning is not available here.** `provisionMySQL` has been removed from the action set: a call carrying it fails schema validation, and a missing instance returns `MYSQL_NOT_CREATED` with a console entry rather than a create hint. **Important:** When creating a new table, you **must** include the `_openid` column for per-user access control: ```sql _openid VARCHAR(64) DEFAULT '' NOT NULL ``` Note: when a user is logged in, `_openid` is automatically populated by the server from the authenticated session. Do not manually fill it in normal inserts. Before calling this tool, **confirm**: - The current environment already has a ready MySQL instance. - The target tables and conditions are correct. - You have run a corresponding read-only query when appropriate. When destroying MySQL, confirm: - The current environment really should lose the SQL instance. - You have explicit confirmation for the destructive action. - You are prepared to query `describeTaskStatus` afterward to inspect the destroy result. ### 3. `queryPermissions` - **Purpose:** Read permission configuration for a given SQL table. - **Use for:** - Understanding who can read/write a table - Auditing permissions on sensitive tables - Call shape: `queryPermissions(action="getResourcePermission", resourceType="sqlDatabase", resourceId="<tableName>")` ### 4. `managePermissions` - **Purpose:** Set or update permissions for a given SQL table. - **Use for:** - Hardening access to sensitive data - Opening up read access while restricting writes - Updating resource-level permission configuration - Call shape: `managePermissions(action="updateResourcePermission", resourceType="sqlDatabase", resourceId="<tableName>", permission="READONLY")` ## Compatibility - Canonical plugin name: `permissions` - Legacy plugin aliases `security-rule`, `security-rules`, `secret-rule`, `secret-rules`, and `access-control` are still routed to `permissions` - Legacy tools `readSecurityRule` and `writeSecurityRule` are removed; always use `queryPermissions` and `managePermissions` --- ## Recommended lifecycle flow ### Scenario 1: The environment has no MySQL instance 1. Call `queryMysqlDatabase(action="getInstanceInfo")`. 2. If no instance exists, **stop**. MySQL provisioning is no longer available through MCP: the result is `MYSQL_NOT_CREATED` with a console entry and no create hint. 3. New environments should use CloudBase PostgreSQL — see `../postgresql-development-cloudbase/SKILL.md`. 4. An instance created outside the tool can still be observed: poll `queryMysqlDatabase(action="describeCreateResult")` or `queryMysqlDatabase(action="describeTaskStatus")`, and only continue once the lifecycle status is `READY`. 5. Reserve `describeTaskStatus` for destroy flows whose task response carries `TaskName`. ### Scenario 2: Safely inspect data in a table 1. Use `queryMysqlDatabase(action="runQuery")` with a limited `SELECT`. 2. Include `LIMIT` and relevant filters. 3. Review the result set and confirm it matches expectations before any write operation. ### Scenario 3: Apply schema initialization on a ready instance 1. Confirm MySQL is ready. 2. Prepare ordered DDL statements. 3. Run them through `manageMysqlDatabase(action="initializeSchema")`. 4. After creating tables, verify permissions with `queryPermissions` or `managePermissions`. ### Scenario 4: Execute a targeted write or DDL change 1. Use `queryMysqlDatabase(action="runQuery")` to inspect current data or schema if needed. 2. Run the mutation once with `manageMysqlDatabase(action="runStatement")`. 3. Validate with another read-only query or by checking security rules. ### Scenario 5: Destroy MySQL when the environment no longer needs it 1. Use `queryMysqlDatabase(action="getInstanceInfo")` to confirm the current environment still has a SQL instance. 2. Call `manageMysqlDatabase(action="destroyMySQL", confirm=true)`. 3. Query `queryMysqlDatabase(action="describeTaskStatus")` until the destroy task completes or fails. 4. If the task succeeds, optionally call `queryMysqlDatabase(action="getInstanceInfo")` to confirm the instance no longer exists. 5. If the task fails, treat the returned error as the terminal result and let the caller decide whether to retry. --- ## Key principle: MCP tools vs SDKs - **MCP tools** are for **agent operations** and **database management**: - Inspect and manage an existing MySQL instance — never create one. - Destroy MySQL. - Poll lifecycle state. - Run ad-hoc SQL. - Inspect and change resource permissions. - Do not depend on application auth state. - **SDKs** are for **application code**: - Frontend Web apps -> Web Relational Database skill. - Backend Node apps -> Node Relational Database quickstart. When working as an MCP agent, **always prefer these MCP tools** for CloudBase Relational Database, and avoid mixing them with SDK initialization in the same flow.