使用 Cloud SQL Data API 执行 SQL 语句

本页面介绍了如何使用 Data API 针对 Cloud SQL 实例上的数据库执行 SQL 语句。借助 Data API，您可以使用 Cloud SQL Admin API 和 gcloud CLI 在已启用 Data API 访问权限的任何实例上运行 SQL 语句。

您可以将 Data API 与使用公共 IP 地址、专用服务访问通道或 Private Service Connect 的实例搭配使用。Data API 支持所有类型的 SQL 语句，包括数据操纵语言 (DML)、数据定义语言 (DDL) 和数据查询语言 (DQL)。Data API 非常适合运行小型快速的管理语句，例如创建数据库角色或用户以及进行小型架构更新。您还可以使用 Data API 来启用 PostgreSQL 扩展程序。

准备工作

在实例上执行 SQL 语句之前，请执行以下操作：

所需的角色或权限

默认情况下，具有以下某个角色的用户或服务账号有权在 Cloud SQL 实例上执行 SQL 语句 (cloudsql.instances.executesql)：

  • Cloud SQL Admin (roles/cloudsql.admin)
  • Cloud SQL Instance User (roles/cloudsql.instanceUser)
  • Cloud SQL Studio User (roles/cloudsql.studioUser)

您还可以为包含 cloudsql.instances.executesql 权限的用户或服务账号定义 IAM 自定义角色。IAM 自定义角色支持此权限。

启用或停用 Data API

如需使用 Data API，您必须为每个实例启用该 API。 您可以随时停用 Data API。

gcloud

如需在实例上启用 Data API 访问权限，请使用带有 --data-api-access=ALLOW_DATA_API 标志的 gcloud sql instances patch 命令：

gcloud sql instances patch INSTANCE_NAME --data-api-access=ALLOW_DATA_API

如需停用 Data API 访问权限，请使用 --data-api-access=DENY_DATA_API 标志：

gcloud sql instances patch INSTANCE_NAME --data-api-access=DENY_DATA_API

将 INSTANCE_NAME 替换为要启用或停用 Data API 的实例的名称。

执行 SQL 语句

您可以使用 gcloud CLI 或 REST API 对 Cloud SQL 实例上的数据库执行 SQL 语句。

gcloud

如需使用 gcloud CLI 对实例上的数据库执行 SQL 语句，请使用 gcloud beta sql instances execute-sql 命令：

gcloud beta sql instances execute-sql INSTANCE_NAME \
--database=DATABASE_NAME \
--sql=SQL_STATEMENT \
--partial_result_mode=PARTIAL_RESULT_MODE

进行以下替换：

  • INSTANCE_NAME：实例的名称。
  • DATABASE_NAME：实例中数据库的名称。
  • SQL_STATEMENT：要执行的 SQL 语句。如果语句包含空格或 shell 特殊字符，则必须用英文引号引起来。
  • PARTIAL_RESULT_MODE：可选。控制结果不完整时的响应方式。可以是 ALLOW_PARTIAL_RESULT、FAIL_PARTIAL_RESULT 或 PARTIAL_RESULT_MODE_UNSPECIFIED。请参阅修改截断行为。

您还可以根据需要添加 --project=PROJECT_ID 标志。

REST

如需使用 REST API 对实例上的数据库执行 SQL 语句，请向 executeSql 端点发送 POST 请求：

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME/executeSql

请求正文应包含数据库名称和 SQL 语句：

{
  "database": "DATABASE_NAME",
  "sqlStatement": "SQL_STATEMENT",
  "partialResultMode": "PARTIAL_RESULT_MODE"
}

进行以下替换：

  • PROJECT_ID：您的项目 ID。
  • INSTANCE_NAME：实例的名称。
  • DATABASE_NAME：实例中数据库的名称。
  • SQL_STATEMENT：要执行的 SQL 语句。
  • PARTIAL_RESULT_MODE：可选。控制当结果超过 10 MB 时 API 的响应方式。可以是 FAIL_PARTIAL_RESULT 或 ALLOW_PARTIAL_RESULT。请参阅修改截断行为。

修改截断行为

您可以控制执行 SQL 时如何处理大型结果。

  • 在请求中添加 "partialResultMode" 字段。此字段接受以下值：
    • FAIL_PARTIAL_RESULT：如果结果超过 10 MB，或者只能检索到部分结果，则抛出错误。不返回结果。
    • ALLOW_PARTIAL_RESULT：如果结果超过 10 MB，或者由于错误只能检索到部分结果，则返回截断的结果并将 partial_result 设置为 true。不抛出错误。

限制

  • 响应的大小上限为 10 MB。如果 partialResultMode 设置为 ALLOW_PARTIAL_RESULT，则超出此大小的结果会被截断，否则会抛出错误。
  • 请求大小上限为 0.5 MB。
  • 您只能对正在运行的 Cloud SQL for PostgreSQL 实例运行 SQL 语句。
  • Cloud SQL 不支持将 Data API 与设置为外部服务器复制的实例搭配使用。
  • 处理时间超过 30 秒的请求会被取消。不支持使用 SET STATEMENT_TIMEOUT 设置更长的语句超时时间。
  • Cloud SQL 将每个用户每个实例的并发 executeSql 请求数限制为 10 个。如果达到此限制，后续请求将失败，并显示“已达到并发读取次数上限 (10)”。
  • 每个响应最多可包含 10 条数据库消息或警告。
  • 如果存在语句语法或执行错误，则不会返回任何结果。
  • 消耗大量内存的语句可能会导致内存不足错误。如需详细了解如何避免这些错误，请参阅管理内存用量的最佳实践。运行内存利用率高的数据库实例通常会导致性能问题、停滞，甚至数据库停机。