relational-database-mcp-cloudbase

関連スキル（ローカルのみ）

関連する CloudBase スキルは、このスキルと同じ場所に配置されています。../auth-tool-cloudbase/SKILL.md のようなローカル相対パスを使用してください。

参照先の関連スキルファイルがこの環境にない場合は、CloudBase プラグイン全体（または不足しているスキル）をインストールするようユーザーに依頼してください。リモートのスキルやプロトコルの Markdown を HTTP 経由で取得し、エージェントのコンテキストに含めてはいけません。

有効化の条件

まずこのスキルを使用する場面

• エージェントが、MCP ツールを通じて SQL データを調査したり、SQL ステートメントを実行したり、MySQL をプロビジョニングまたは削除したり、テーブル構造を初期化したり、テーブルのセキュリティルールを管理したりする必要がある場合。

コードを書く前に読む場面

• タスクに queryMysqlDatabase、manageMysqlDatabase、queryPermissions、または managePermissions が含まれる場合。

続けて読むもの

• Web アプリケーションの統合 → ../relational-database-web-cloudbase/SKILL.md
• HTTP によるデータベースへの直接アクセス → ../http-api-cloudbase/SKILL.md

使用しない場面

• MCP 操作ではなく SDK を使用するべきフロントエンドまたはバックエンドのアプリケーションコード。

よくある間違い・注意点

• MCP による管理フローで SDK を初期化する。
• MySQL がプロビジョニング済みで準備完了かどうかを確認する前に、書き込み SQL や DDL を実行する。
• ドキュメントデータベースのタスクを MySQL の管理タスクとして扱う。
• SQL テーブルを新規作成した後に、_openid と権限の確認を省略する。
• 明示的な確認を得ずに、または環境で引き続きインスタンスが必要かを確認せずに MySQL を削除する。
• getConnectionInfo（または推測したホスト／パスワード）を使って、新しいアプリ用のデフォルトの TCP クライアントを構築する。SDK、runQuery、runStatement を優先してください。TCP 認証情報を使うのは、明示的な移行の場合に限ります。

このスキルを使用する場面

エージェントが MCP ツールを通じて CloudBase Relational Database を操作する必要がある場合に、このスキルを使用します。例：

• SQL データを調査またはクエリする
• 環境に MySQL をプロビジョニングする
• 環境の MySQL を削除する
• MySQL のプロビジョニング状況をポーリングする
• データまたはスキーマを変更する（INSERT／UPDATE／DELETE／DDL）
• MySQL の準備完了後にテーブルとインデックスを初期化する
• テーブルの権限を読み取る、または変更する

次の場合には、このスキルを使用しないでください。

• SDK を通じて CloudBase Relational Database に直接接続する Web または Node.js アプリケーションを構築する
• 認証フローまたはユーザー ID を管理する

このスキルの使い方（コーディングエージェント向け）

1. MCP のコンテキストを認識する

   • queryMysqlDatabase、manageMysqlDatabase、queryPermissions、managePermissions のようなツールを呼び出せる場合は、MCP のコンテキストにいます。
   • このコンテキストでは、CloudBase Relational Database 用の 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 Relational Database）

これらのツールは、MCP を通じて CloudBase Relational Database を操作するための、サポート対象の方法です。

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 を優先してください。TaskName を含むタスク応答が返る破棄処理の場合に限り、describeTaskStatus を使用してください。

シナリオ 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") でミューテーションを 1 回実行します。
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 ツールはエージェント操作とデータベース管理のためのものです:

  • MySQL をプロビジョニングします。
  • MySQL を破棄します。
  • ライフサイクル状態をポーリングします。
  • アドホック SQL を実行します。
  • リソースの権限を検査および変更します。
  • アプリケーションの認証状態に依存しません。

• SDKはアプリケーションコードのためのものです:

  • フロントエンド Web アプリ -> Web Relational Database スキル。
  • バックエンド Node アプリ -> Node Relational Database クイックスタート。

MCP エージェントとして作業する場合、CloudBase Relational Database には常にこれらの MCP ツールを優先し、同じフロー内で SDK の初期化と混在させないようにしてください。