使用 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 语句。

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

准备工作

如需在实例上执行 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 = "MYSQL_8_4"

  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.
 */
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.
  # This field doesn't support MySQL 5.6 and 5.7.
  database_roles = ["cloudsqlsuperuser"]
}

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 DATABASE pets;"
  instance = google_sql_database_instance.instance.name

  # Some of your queries may require a database. You can create and use a
  # database in the script or explicitly create and reference a database
  # like database = google_sql_database.database.name.

  description = "sql script to create DBs"

  # 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 MySQL 实例运行 SQL 语句。
Cloud SQL 不支持将 Data API 与设置为外部服务器复制的实例搭配使用。
耗时超过 30 秒的请求会被取消。不支持使用 SET SESSION MAX_EXECUTION_TIME 设置更高的语句超时时间。对于 Cloud SQL for MySQL 5.6 和 5.7，长时间运行的 DDL 语句超时可能会导致出现无法安全回滚的孤立文件或表。请谨慎使用针对大型表的 ALTER TABLE 等语句。
Cloud SQL 将每个用户每个实例的并发 executeSql 请求数限制为 10 个。如果达到此限制，后续请求将失败，并显示“At most 10 concurrent queries may be run on this instance. Try again later.”（此实例上最多可以运行 10 个并发查询。
请稍后重试。）或“Maximum concurrent reads 10 reached.”（已达到并发读取上限 10。）
如果存在语句语法或执行错误，则不返回任何结果。
对于 Cloud SQL for MySQL，仅多语句执行的最后一条语句提供通知和警告。
对于 Cloud SQL for MySQL，通知和警告仅适用于多语句执行的最后一条语句。消耗大量内存的语句可能会导致内存不足错误。如需详细了解如何避免这些错误，请参阅管理内存用量的最佳实践。
在实例上进行某些维护操作时，出于数据完整性目的，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 语句