MCP Tools Reference: cloud-sql

工具：execute_sql

在 Cloud SQL 实例上执行任何有效的 SQL 语句，包括数据定义语言 (DDL)、数据控制语言 (DCL)、数据查询语言 (DQL) 或数据操纵语言 (DML) 语句。

如需支持 execute_sql 工具，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 工具。该工具会使用通过 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”（实例不允许使用 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 工具或 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 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”结尾。示例："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 唯一标识序列化协议缓冲区消息类型的网址/资源名称。此字符串必须包含至少一个“/”字符。网址路径的最后一段必须表示类型的完全限定名称（如 path/google.protobuf.Duration 中所示）。该名称应采用规范形式（例如，不接受前导“.”）。 在实践中，团队通常会预先将他们希望在 Any 的上下文中使用的所有类型编译到二进制文件中。不过，对于使用 http、https 方案或不使用方案的网址，可以选择性地设置一个类型服务器，该服务器可将类型网址映射到消息定义，如下所示： 如果未提供方案，则假定为 https。 对相应网址执行 HTTP GET 操作必须生成二进制格式的 google.protobuf.Type 值，否则会产生错误。 应用可以缓存基于网址的查找结果，也可以将这些结果预编译到二进制文件中，以避免任何查找。因此，在更改类型时需要保持二进制兼容性。（使用版本化类型名称来管理重大更改。） 注意：此功能目前在正式版 protobuf 中尚不可用，并且不适用于以 type.googleapis.com 开头的类型网址。截至 2023 年 5 月，尚无广泛使用的类型服务器实现，也没有实现计划。 除了 http、https（或空方案）之外的方案可能会与特定于实现的语义搭配使用。
value	string (bytes format) 必须是上述指定类型的有效序列化协议缓冲区。 使用 base64 编码的字符串。

工具注释

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