MCP Tools Reference: cloud-sql

ツール: execute_sql

Cloud SQL インスタンスで、データ定義言語（DDL）、データ制御言語（DCL）、データクエリ言語（DQL）、データ操作言語（DML）のステートメントなど、有効な SQL ステートメントを実行します。

execute_sql ツールをサポートするには、Cloud SQL インスタンスが次の要件を満たしている必要があります。

  • data_api_access の値は ALLOW_DATA_API に設定する必要があります。
  • MySQL インスタンスの場合、データベース フラグ cloudsql_iam_authentication は on に設定する必要があります。PostgreSQL インスタンスの場合、データベース フラグ cloudsql.iam_authentication は on に設定する必要があります。
  • execute_sql ツールを呼び出すには、IAM ユーザー アカウントまたは IAM サービス アカウント（CLOUD_IAM_USER または CLOUD_IAM_SERVICE_ACCOUNT）が必要です。このツールは、IAM データベース認証でログインしたデータベース ユーザーの権限を使用して SQL ステートメントを実行します。

create_instance ツールを使用してインスタンスを作成したら、create_user ツールを使用して、現在プロジェクトにログインしているユーザーの IAM ユーザー アカウントを作成できます。

execute_sql ツールには次の制限があります。

  • SQL ステートメントが 10 MB を超えるレスポンスを返すと、レスポンスは切り捨てられます。
  • execute_sql ツールのデフォルトのタイムアウトは 30 秒です。クエリの実行時間が 30 秒を超えると、ツールは DEADLINE_EXCEEDED エラーを返します。
  • execute_sql ツールは SQL Server ではサポートされていません。

「IAM 認証がインスタンスで有効になっていません」のようなエラーが表示された場合は、get_instance ツールを使用して、インスタンスの IAM データベース認証フラグの値を確認できます。

「The instance doesn't allow using executeSql to access this instance」などのエラーが表示された場合は、get_instance ツールを使用して data_api_access 設定を確認できます。

認証エラーが発生した場合:

  1. list_users ツールを使用して、現在ログインしているユーザー アカウントがインスタンスの IAM ユーザーとして存在するかどうかを確認します。
  2. IAM ユーザー アカウントが存在しない場合は、create_user ツールを使用して、ログイン ユーザーの IAM ユーザー アカウントを作成します。
  3. 現在ログインしているユーザーに適切なデータベース ユーザーロールがない場合は、update_user ツールを使用してユーザーにデータベース ロールを付与できます。たとえば、cloudsqlsuperuser ロールは、IAM ユーザーに必要な多くの権限を付与できます。

  4. 現在ログインしているユーザーに、プロジェクトに割り当てられている適切な IAM 権限があるかどうかを確認します。gcloud projects get-iam-policy [PROJECT_ID] コマンドを使用して、ユーザーにプロジェクトに対する適切な IAM ロールまたは権限が割り当てられているかどうかを確認できます。

    • 自動 IAM データベース認証を行うには、ユーザーに cloudsql.instance.login 権限が必要です。
    • execute_sql ツールまたは executeSql API を使用して SQL ステートメントを実行するには、cloudsql.instances.executeSql 権限が必要です。
    • 必要な権限を含む一般的な IAM ロール: Cloud SQL インスタンス ユーザー（roles/cloudsql.instanceUser）または Cloud SQL 管理者（roles/cloudsql.admin）

ExecuteSqlResponse を受け取った場合は、レスポンスの本文内の message フィールドと status フィールドを必ず確認してください。HTTP ステータス コードが成功を示していても、すべての SQL ステートメントが完全に成功するとは限りません。message フィールドと status フィールドは、SQL ステートメントの実行中に部分的なエラーまたは警告が発生したかどうかを示します。

次のサンプルは、curl を使用して execute_sql MCP ツールを呼び出す方法を示しています。

Curl リクエスト 
                  
curl --location 'https://sqladmin.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "execute_sql",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

入力スキーマ

MCP のインスタンス実行 SQL リクエスト。

SqlInstancesExecuteSqlMcpRequest

JSON 表現 
{
  "instance": string,
  "project": string,
  "sqlStatement": string,
  "database": string
}
フィールド
instance

string

必須。データベース インスタンス ID。プロジェクト ID は含みません。
project

string

必須。インスタンスを含むプロジェクトのプロジェクト ID。
sqlStatement

string

必須。データベースで実行する SQL ステートメント。単一のステートメントまたはセミコロンで区切られたステートメントのシーケンスを指定できます。
database

string

省略可。ステートメントが実行されるデータベースの名前。Postgres では必須ですが、MySQL では省略可能です。Postgres の場合、クエリが既存のデータベース（データベースのリスト表示、新しいデータベースの作成、ロールの付与など）にスコープ設定されていない場合は、デフォルト値として postgres を渡すことができます。

出力スキーマ

SQL ステートメントの実行のレスポンス。

SqlInstancesExecuteSqlResponse

JSON 表現 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "results": [
    {
      object (QueryResult)
    }
  ],
  "status": {
    object (Status)
  }
}
フィールド
messages[]

object (Message)

クエリ実行中に生成された通知と警告のリスト。PostgreSQL の場合、これにはすべての通知と警告が含まれます。MySQL の場合、これには最後に実行されたステートメントによって生成された警告が含まれます。マルチステートメント クエリのすべての警告を取得するには、各ステートメントの後に SHOW WARNINGS を実行する必要があります。
metadata

object (Metadata)

SQL ステートメントの実行に関する追加のメタデータ情報。
results[]

object (QueryResult)

すべての SQL ステートメントを実行した後の結果のリスト。
status

object (Status)

SQL 実行が失敗した場合、データベースからのエラーが含まれます。

メッセージ

JSON 表現 
{

  // Union field _message can be only one of the following:
  "message": string
  // End of list of possible types for union field _message.

  // Union field _severity can be only one of the following:
  "severity": string
  // End of list of possible types for union field _severity.
}
フィールド

共用体フィールド _message。

_message は次のいずれかになります。
message

string

メッセージ文字列の全文。PostgreSQL の場合、これは重大度、コード、通知/警告メッセージを含む書式設定された文字列です。MySQL の場合、これには警告メッセージが含まれます。

共用体フィールド _severity。

_severity は次のいずれかになります。
severity

string

メッセージの重大度（PostgreSQL の場合は「NOTICE」、MySQL の場合は「WARNING」）。

メタデータ

JSON 表現 
{
  "sqlStatementExecutionTime": string
}
フィールド
sqlStatementExecutionTime

string (Duration format)

SQL ステートメントの実行にかかった時間。

s で終わる小数 9 桁までの秒単位の期間。例: "3.5s"。

所要時間

JSON 表現 
{
  "seconds": string,
  "nanos": integer
}
フィールド
seconds

string (int64 format)

期間の符号付き秒数。-315,576,000,000 ～+315,576,000,000 の範囲（両端を含む）にする必要があります。注: これらの境界は、60 秒/分 * 60 分/時間 * 24 時間/日 * 365.25 日/年 * 10,000 年から計算されます。
nanos

integer

期間のナノ秒分解能による、秒の符号付き小数以下部分。1 秒未満の期間は、0 の seconds フィールドと正または負の nanos フィールドで表されます。1 秒以上の期間の場合、nanos フィールドのゼロ以外の値は、seconds フィールドと同じ符号である必要があります。-999,999,999～+999,999,999 の範囲内（境界含む）である必要があります。

QueryResult

JSON 表現 
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "message": string,
  "partialResult": boolean,
  "status": {
    object (Status)
  }
}
フィールド
columns[]

object (Column)

結果に含まれる列のリスト。これには、列のデータ型も含まれます。
rows[]

object (Row)

SQL ステートメントによって返された行。
message

string

SQL 実行結果に関連するメッセージ。
partialResult

boolean

サイズ上限または結果の取得エラーにより SQL 実行の結果が切り捨てられた場合は true に設定します。
status

object (Status)

エラーが原因で結果が切り捨てられた場合は、そのエラーの詳細。

列

JSON 表現 
{
  "name": string,
  "type": string
}
フィールド
name

string

列の名前です。
type

string

列のデータ型。

行

JSON 表現 
{
  "values": [
    {
      object (Value)
    }
  ]
}
フィールド
values[]

object (Value)

行の値。

値

JSON 表現 
{
  "value": string,
  "nullValue": boolean
}
フィールド
value

string

文字列形式のセル値。
nullValue

boolean

セルの値が null の場合、このフラグは true に設定されます。

ステータス

JSON 表現 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
フィールド
code

integer

ステータス コード。google.rpc.Code の列挙値である必要があります。
message

string

デベロッパー向けのエラー メッセージ。英語で記述します。ユーザー向けのエラー メッセージは、ローカライズして google.rpc.Status.details フィールドで送信するか、クライアントでローカライズする必要があります。
details[]

object

エラーの詳細を保持するメッセージのリスト。API が使用する共通のメッセージ タイプのセットがあります。

任意のデータ型のフィールドを含むオブジェクトであり、型を識別する URI を含むフィールド "@type" を追加できます。例: { "id": 1234, "@type": "types.example.com/standard/id" }

すべて

JSON 表現 
{
  "typeUrl": string,
  "value": string
}
フィールド
typeUrl

string

シリアル化されたプロトコル バッファ メッセージのタイプを一意に識別する URL またはリソース名。この文字列には、少なくとも 1 つの「/」文字を含める必要があります。URL のパスの最後のセグメントは、型の完全修飾名（path/google.protobuf.Duration など）を表す必要があります。名前は正規形にする必要があります（先頭の「.」は使用できません）。

実際には、チームは通常、Any のコンテキストで使用されることが想定されるすべての型をバイナリにプリコンパイルします。ただし、スキーム http、https、またはスキームを使用しない URL の場合は、次のように型 URL をメッセージ定義にマッピングする型サーバーをオプションで設定できます。

  • スキームが指定されていない場合、https であると見なされます。
  • URL の HTTP GET は、バイナリ形式の google.protobuf.Type 値を返すか、エラーを生成する必要があります。
  • アプリケーションは URL に基づいて検索結果をキャッシュに格納するか、検索結果をバイナリに事前コンパイルして検索を回避することができます。このため、型を変更する場合は、バイナリ互換性を維持する必要があります（互換性を破る変更を管理するためバージョン付き型名を使用してください）。

注: この機能は現在のところ公式の protobuf リリースでは利用できません。また、type.googleapis.com で始まるタイプ URL には使用されません。2023 年 5 月の時点で、広く使用されているタイプ サーバーの実装はなく、実装の予定もありません。

http、https（または空のスキーム）以外のスキームは、実装固有のセマンティクスで使用される場合があります。
value

string (bytes format)

上記の指定された型の有効なシリアル化されたプロトコル バッファである必要があります。

Base64 でエンコードされた文字列。

ツールのアノテーション

破壊的ヒント: ✅ | べき等ヒント: ❌ | 読み取り専用ヒント: ❌ | オープン ワールド ヒント: ❌