MCP Tools Reference: cloud-sql

ツール: execute_sql_readonly

Cloud SQL インスタンスで有効な読み取り専用 SQL ステートメントを実行する。

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

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

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

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

  • SQL ステートメントが 10 MB を超えるレスポンスを返すと、レスポンスは切り捨てられます。
  • このツールのデフォルトのタイムアウトは 30 秒です。クエリの実行時間が 30 秒を超えると、ツールは DEADLINE_EXCEEDED エラーを返します。
  • このツールは 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_readonly ツールまたは 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_readonly 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_readonly",
    "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,
  "user": string,
  "passwordSecretVersion": string
}
フィールド
instance

string

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

string

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

string

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

string

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

string

省略可。データベースに接続する既存のデータベース ユーザーの名前。auto_iam_authn が true に設定されている場合、このフィールドは無視され、API 呼び出し元の IAM ユーザーが使用されます。
passwordSecretVersion

string

省略可。データベースにログインするユーザーのパスワードを保持する Secret Manager シークレットのリソース名。projects/{project}/secrets/{secret}/versions/{secret_version} という形式で指定してください。シークレット リソース名は保存されません。

出力スキーマ

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

スラッシュで終わる接頭辞と完全修飾型名で構成される URI 参照で、シリアル化された Protobuf メッセージの型を識別します。

例: type.googleapis.com/google.protobuf.StringValue

この文字列には / 文字を 1 つ以上含める必要があります。最後の / の後の内容は、先頭のドットのない正規形式の型の完全修飾名にする必要があります。クライアントが連絡を試みないように、これらの URI 参照にスキームを記述しないでください。

接頭辞は任意であり、Protobuf 実装では、最後の / までをすべて削除して型を識別することが想定されています。type.googleapis.com/ は、一部のレガシー実装で必要な一般的なデフォルトの接頭辞です。この接頭辞は型のオリジンを示すものではなく、これを含む URI はリクエストに応答しないことが想定されています。

すべての型 URL 文字列は、有効な URI 参照である必要があります。テキスト形式の場合、参照の内容は英数字、パーセント エンコードされたエスケープ、次のセットの文字（外側のバッククォートを除く）/-.~_!$&()*+,;= のみで構成されている必要があります。パーセント エンコードは許可されていますが、既存のパーサーとの混同を避けるため、実装ではエスケープ解除しないでください。たとえば、type.googleapis.com%2FFoo は拒否される必要があります。

Any の元の設計では、これらの型 URL で型解決サービスを起動する可能性が検討されましたが、Protobuf は実装していません。これらの URL へのアクセスは問題があり、セキュリティ上の問題を引き起こす可能性があると見なされています。連絡先タイプの URL にアクセスしないでください。
value

string (bytes format)

type_url で記述された型の Protobuf シリアル化を保持します。

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

ツールのアノテーション

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