relational-database-mcp-cloudbase

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

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

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

有効化の条件

まずこのスキルを使う場合

• エージェントが SQL データを調査する、SQL 文を実行する、既存の MySQL インスタンスを破棄する、テーブル構造を初期化する、または MCP ツールでテーブルのセキュリティルールを管理する必要がある場合です。

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

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

その後、こちらも読む

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

使用しない場合

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

よくある間違い・注意点

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

このスキルを使う場合

エージェントが MCP ツール経由で CloudBase Relational Database を操作する必要がある場合に、このスキルを使用します。たとえば、次のような場合です。

• SQL データの調査またはクエリ
• 既存の MySQL インスタンスの破棄
• 実行中の MySQL タスクの状態確認（作成タスクはコンソールで開始します。MCP ではインスタンスを作成できなくなりました）
• データまたはスキーマの変更（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 の破棄、書き込み 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="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 ツールは、エージェントの操作とデータベース管理に使用します。

  • 既存の MySQL インスタンスを確認、管理します。作成はしません。
  • MySQL を破棄します。
  • ライフサイクルの状態をポーリングします。
  • アドホックな SQL を実行します。
  • リソースの権限を確認、変更します。
  • アプリケーションの認証状態に依存しません。

• SDKは、アプリケーションコードに使用します。

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

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