使用 Cloud SQL Data API 执行 SQL 语句

MySQL | PostgreSQL | SQL Server

本页面介绍了如何使用 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 语句之前，请执行以下操作：

为实例配置 IAM 数据库身份验证。
向实例添加 IAM 用户或服务账号，并向该账号授予执行 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。

控制台

在 Google Cloud 控制台中，前往 Cloud SQL 实例页面。

转到“Cloud SQL 实例”
如需打开实例的概览页面，请点击实例名称。
从 SQL 导航菜单中选择连接。
点击网络标签页。
选中允许 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=DISALLOW_DATA_API 标志：

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

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

执行 SQL 语句

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

gcloud

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

gcloud 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 标志。

Terraform

您可以在 Terraform 上使用 Data API 来预配数据库内资源，例如数据库、表、扩展程序、用户和权限授予，而无需手动连接到实例。如需在 Terraform 上执行 SQL 脚本，请使用 google_sql_provision_script Terraform 资源。

resource "google_sql_database_instance" "instance" {
  name             = "my-instance"
  database_version = "POSTGRES_17"

  settings {
    tier            = "db-perf-optimized-N-2"
    data_api_access = "ALLOW_DATA_API"  # This allows the use of Data API.
    database_flags {
      name  = "cloudsql.iam_authentication"
      value = "on"
    }
  }
}

/*
 * Create a database user for your account and grant roles so it has privilege to
 * access the database. Set the type to CLOUD_IAM_USER for huamn account or
 * CLOUD_IAM_SERVICE_ACCOUNT for service account. If a service account is used
 * and the instance is Postgres, trim the ".gserviceaccount.com"
 * suffix to avoid exceeding the username length limit.
*/
resource "google_sql_user" "iam_user" {
  name     = "account-used-to-apply-this-config@example.com"
  instance = google_sql_database_instance.instance.name
  type     = "CLOUD_IAM_USER"

  # Roles granted to the user. Smaller roles are preferred, if exist.
  database_roles = ["cloudsqlsuperuser"]
}

resource "google_sql_database" "database" {
  name     = "my-database"
  instance = google_sql_database_instance.instance.name
}

resource "google_sql_provision_script" "script" {
  # You can inline the script or import from a file like script  = file("${path.module}/script.sql")
  # When modified, the whole script will be executed again. It's recommended to
  # make the script idempotent with patterns like create if not exists ... or
  # if not exists (select ...) then ... end if.
  script  = "CREATE TABLE IF NOT EXISTS table1 ( col VARCHAR(16) NOT NULL );"

  instance = google_sql_database_instance.instance.name
  database = google_sql_database.database.name
  description = "sql script to create tables"

  # The identity account used to apply your Terraform config must exist as an
  # IAM user or IAM service account in the instance. Terraform connects to the
  # instance via IAM database authentication to execute the script.
  depends_on = [google_sql_user.iam_user]
}

应用更改

如需在 Google Cloud 项目中应用 Terraform 配置，请完成以下部分中的步骤。

准备 Cloud Shell

启动 Cloud Shell。
设置要应用 Terraform 配置的默认 Google Cloud 项目。

您只需为每个项目运行一次以下命令，即可在任何目录中运行它。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
如果您在 Terraform 配置文件中设置显式值，则环境变量会被替换。

准备目录

每个 Terraform 配置文件都必须有自己的目录（也称为“根模块”）。

在 Cloud Shell 中，创建一个目录，并在该目录中创建一个新文件。文件名必须具有 .tf 扩展名，例如 main.tf。在本教程中，该文件称为 main.tf。
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
如果您按照教程进行操作，可以在每个部分或步骤中复制示例代码。

将示例代码复制到新创建的 main.tf 中。

（可选）从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段，则建议这样做。
查看和修改要应用到您的环境的示例参数。
保存更改。
初始化 Terraform。您只需为每个目录执行一次此操作。
```
terraform init
```
（可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：
```
terraform init -upgrade
```

应用更改

查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：
```
terraform plan
```
根据需要更正配置。
通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：
```
terraform apply
```
等待 Terraform 显示“应用完成！”消息。
打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

删除更改

删除 google_sql_provision_script 资源不会删除其创建的数据库内资源。如需删除它们，您可以在脚本中明确添加 drop ... if exists 等语句，然后应用更改。

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"
  "autoIamAuthn": true
}

进行以下替换：

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。”
每个响应最多可包含 10 条数据库消息或警告。
如果存在语句语法或执行错误，则不会返回任何结果。
消耗大量内存的语句可能会导致内存不足错误。如需详细了解如何避免这些错误，请参阅管理内存用量的最佳实践。运行内存利用率高的数据库实例通常会导致性能问题、停滞，甚至数据库停机。
当实例上正在进行某些维护操作时，出于数据完整性考虑，Data API 可能会暂时被屏蔽。如果发生这种情况，请稍后重试。
Data API 尚无法保证数据驻留。对于某些 Assured Workloads 项目以及具有 constraints/sql.restrictNoncompliantResourceCreation 手动强制执行的项目，请求将失败，并显示错误“不支持某些 Assured Workloads 控制措施套餐文件夹中的实例”。

使用 Cloud SQL Data API 执行 SQL 语句 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色或权限

启用或停用 Data API

控制台

gcloud

执行 SQL 语句

gcloud

Terraform

应用更改

准备 Cloud Shell

准备目录

应用更改

删除更改

REST

修改截断行为

限制

使用 Cloud SQL Data API 执行 SQL 语句