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。
  • 您需要使用 IAM 用户账号或 IAM 服务账号（CLOUD_IAM_USER 或 CLOUD_IAM_SERVICE_ACCOUNT）来调用 execute_sql_readonly 工具。该工具会使用通过 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”（实例不允许使用 executeSql 访问此实例）等错误，可以使用 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 角色或权限。

    • 用户必须拥有 cloudsql.instance.login 权限才能进行自动 IAM 数据库身份验证。
    • 用户必须拥有 cloudsql.instances.executeSql 权限，才能使用 execute_sql_readonly 工具或 executeSql API 执行 SQL 语句。
    • 包含所需权限的常见 IAM 角色：Cloud SQL Instance User (roles/cloudsql.instanceUser) 或 Cloud SQL Admin (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”结尾。示例："3.5s"。

时长

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

时间段的带符号秒数。必须介于 -315,576,000,000 到 +315,576,000,000 之间（含边界值）。注意：这些界限的计算依据是：60 秒/分钟 * 60 分钟/小时 * 24 小时/天 * 365.25 天/年 * 10000 年
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 使用。

可以包含任意类型字段的对象。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

不限

JSON 表示法 
{
  "typeUrl": string,
  "value": string
}
字段
typeUrl

string

通过 URI 引用（包含以斜杠结尾的前缀和完全限定的类型名称）来标识序列化 Protobuf 消息的类型。

示例：type.googleapis.com/google.protobuf.StringValue

此字符串必须包含至少一个 / 字符，并且最后一个 / 之后的内容必须是规范形式的完全限定名，不含前导点。请勿在这些 URI 引用中写入方案，以免客户端尝试联系它们。

前缀是任意的，Protobuf 实现应仅剥离最后一个 / 之前（包括）的所有内容，以识别类型。type.googleapis.com/ 是某些旧版实现所需的常见默认前缀。此前缀并不表示类型的来源，包含该前缀的 URI 不应响应任何请求。

所有类型网址字符串都必须是合法的 URI 引用，并且（对于文本格式）还必须满足以下额外限制：引用的内容只能包含字母数字字符、百分号编码的转义字符以及以下集合中的字符（不包括外侧的反引号）：/-.~_!$&()*+,;=。尽管我们允许使用百分比编码，但实现不应将其转义，以免与现有解析器混淆。例如，应拒绝 type.googleapis.com%2FFoo。

在 Any 的原始设计中，曾考虑过在这些类型网址上启动类型解析服务的可能性，但 Protobuf 从未实现过此类服务，并且认为联系这些网址存在问题，可能会导致安全问题。不尝试联系人类型网址。
value

string (bytes format)

包含由 type_url 描述的类型的 Protobuf 序列化。

使用 base64 编码的字符串。

工具注释

破坏性提示：❌ | 等幂性提示：✅ | 只读提示：✅ | 开放世界提示：❌