Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用 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 非常适合运行小型快速管理语句，例如创建数据库角色或用户以及进行小型架构更新。您还可以使用 Data API 启用 PostgreSQL 扩展程序。

注意在外部身份提供方中管理用户访问权限时，请将 Google 账号主账号标识符（例如 user:kiran@example.com、group:support@example.com 和 domain:example.com）替换为适当的员工身份联合主账号标识符。

准备工作

如需在实例上执行 SQL 语句，请执行以下步骤。

配置数据库用户

Data API 需要以数据库用户的身份进行身份验证，才能执行 SQL 语句。您可以内置用户、IAM 用户、IAM 服务帐号或 IAM 群组的身份进行身份验证。

如需使用 IAM 进行身份验证，请执行以下操作：

为实例配置 IAM 数据库身份验证。
向实例添加 IAM 用户、服务帐号或群组。
向账号授予执行 SQL 语句所需的角色或权限。您可以在创建账号或更新账号时分配数据库角色。如果您已创建具有最低权限的自定义数据库角色，请将其分配给账号。否则，请将预定义的 cloudsqlsuperuser 角色分配给账号，使用 Data API 创建具有较低权限的新自定义数据库角色，然后将新角色授予账号以取代 cloudsqlsuperuser。

如需使用密码以内置用户的身份进行身份验证，请执行以下操作：

创建一个具有非空密码的用户账号。您还可以使用默认用户 postgres。
向账号授予执行 SQL 语句所需的角色或权限。您可以在创建账号或更新账号时分配数据库角色。如果您已创建具有最低权限的自定义数据库角色，请将其分配给账号。否则，请将预定义的 cloudsqlsuperuser 角色分配给账号，使用 Data API 创建具有较低权限的新自定义数据库角色，然后将新角色授予账号以取代 cloudsqlsuperuser。
使用 Secret Manager 创建区域级 Secret 以存储密码。出于安全考虑，Data API 会在 API 请求中请求 Secret 的资源名称，而不是密码。区域级 Secret 应存储在与您的 Cloud SQL 实例相同的区域中。即使使用 Secret Manager 的全局端点创建的 Secret 存储在同一区域中，也不受支持。
最佳实践是定义 IAM 条件，以允许用户访问特定 Secret，但不能访问项目中的其他 Secret。

所需的角色或权限

默认情况下，具有以下任一角色的用户或服务账号有权在 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 语句。

使用 IAM 进行身份验证

您可以使用 IAM 数据库身份验证执行 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. For least privilege, you can create smaller roles
  # and then assign them to this user in place of `cloudsqlsuperuser`.
  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 或 PARTIAL_RESULT_MODE_UNSPECIFIED。请参阅修改截断行为。

使用密码进行身份验证

当密码作为区域级 Secret 存储在与 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 \
--user=USER \
--password-secret-version=PASSWORD_SECRET_VERSION \
--partial-result-mode=PARTIAL_RESULT_MODE

进行以下替换：

INSTANCE_NAME：实例的名称。
DATABASE_NAME：实例中的数据库名称。
SQL_STATEMENT：要执行的 SQL 语句。如果语句包含空格或 Shell 特殊字符，则必须用英文引号引起来。
USER：要以其身份进行身份验证的数据库用户。
PASSWORD_SECRET_VERSION：Secret Manager Secret 的资源名称，其中包含数据库用户的密码。Secret 应为a 区域级 Secret，并存储在与 Cloud SQL 实例相同的区域中。预期的资源名称格式为 projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}.
PARTIAL_RESULT_MODE：可选。控制在结果不完整时的响应方式。可以是 ALLOW_PARTIAL_RESULT、FAIL_PARTIAL_RESULT 或 PARTIAL_RESULT_MODE_UNSPECIFIED。请参阅修改截断行为。

Terraform

resource "google_sql_user" "built_in_user" {
  name     = "tf-user"
  host     = "%"  # Don't set this field for PostgreSQL and SQL Server.
  instance = google_sql_database_instance.instance.name
  password = "changeme"
  type     = "BUILT_IN"
}

# Create a regional secret. Global secrets are not supported even if
# located in one region only.
resource "google_secret_manager_regional_secret" "secret" {
  secret_id = "db-password"

  # Use the same region as the Cloud SQL instance.
  location = "us-central1"
}

resource "google_secret_manager_regional_secret_version" "secret_version" {
  secret = google_secret_manager_regional_secret.secret.id
  secret_data = "changeme"
}

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"
  user = google_sql_user.built_in_user.name

  # The location should be the same as the Cloud SQL instance's location.
  password_secret_version = "projects/my-project/locations/us-central1/secrets/db-password/versions/latest"

  # The built-in database user and password secret version must be created
  # first. Cloud SQL will retrieve password from Secret Manager
  # and connect to this user account to execute your script.
  depends_on = [
    google_sql_user.built_in_user,
    google_secret_manager_regional_secret_version.secret_version
  ]
}

应用更改

如需在 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 已创建或更新它们。

删除更改

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",
  "user": "USER",
  "passwordSecretVersion": "PASSWORD_SECRET_VERSION",
  "partialResultMode": "PARTIAL_RESULT_MODE"
}

进行以下替换：

PROJECT_ID：您的项目 ID。
INSTANCE_NAME：实例的名称。
DATABASE_NAME：实例中的数据库名称。
SQL_STATEMENT：要执行的 SQL 语句。
USER：要以其身份进行身份验证的数据库用户。
PASSWORD_SECRET_VERSION：Secret Manager Secret 的资源名称，其中包含数据库用户的密码。Secret 应为a 区域级 Secret，并存储在与 Cloud SQL 实例相同的区域中。预期的资源名称格式为 projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}.
PARTIAL_RESULT_MODE：可选。控制当结果超过 10 MB 时 API 的响应方式。可以是 FAIL_PARTIAL_RESULT、 ALLOW_PARTIAL_RESULT 或 PARTIAL_RESULT_MODE_UNSPECIFIED。请参阅修改截断行为。

修改截断行为

您可以在请求中添加 "partialResultMode"字段，以控制执行 SQL 时如何处理大型结果。此字段接受以下值：

FAIL_PARTIAL_RESULT：默认值。如果结果超过 10 MB 或只能检索部分结果，则抛出错误。不返回结果。
ALLOW_PARTIAL_RESULT：如果结果超过 10 MB 或因错误而只能检索部分结果，则返回截断的结果并将 partial_result 设置为 true。不抛出错误。
PARTIAL_RESULT_MODE_UNSPECIFIED：未指定的模式，实际上与 FAIL_PARTIAL_RESULT 相同。

限制

响应的大小上限为 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 请求数量，以防止过载。如果达到限制，后续请求会失败并返回以下错误之一：
- At most 'x' concurrent queries may be run on this instance. Try again later.
- Maximum concurrent reads 'x' reached.
限制 (x) 为每个实例 10 个查询。
每个响应最多可以包含 10 条数据库消息或警告。
如果存在语句语法或执行错误，则不会返回任何结果。
Data API 无法以密码为空的内置用户身份进行身份验证。
消耗大量内存的语句可能会导致内存不足错误。如需详细了解如何避免这些错误，请参阅管理内存用量的最佳实践。运行内存利用率高的数据库实例通常会导致性能问题、停滞，甚至数据库停机。
当实例上正在进行某些维护操作时，Data API 可能会暂时被阻止，以确保数据完整性。如果发生这种情况，请稍后重试。

如果您在查询编辑器中同时运行多个语句，并且一个或多个语句导致错误，则所有语句的执行会中止，并且系统会显示第一个出现的错误。
当数据库服务器检测到无效的查询语法时，它会在 postgres.log 中生成日志。这些条目显示为 cloudsqladmin 条目，包含无效的查询、语法错误的位置以及相应的错误消息。如需从视图中移除这些日志，请配置日志过滤器以排除 cloudsqladmin 数据库、cloudsqladmin 用户或两者。

SQL 脚本及其执行响应可能会在客户端与目标实例的位置之间经过中间位置。因此，对于某些 Assured Workloads 项目以及手动强制执行 constraints/sql.restrictNoncompliantResourceCreation 的项目，请求将失败并显示错误“not supported for instances in certain Assured Workloads control packages folders”。

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

准备工作

配置数据库用户

所需的角色或权限

启用或停用 Data API

控制台

gcloud

执行 SQL 语句

使用 IAM 进行身份验证

gcloud

Terraform

应用更改

准备 Cloud Shell

准备目录

应用更改

删除更改

REST

使用密码进行身份验证

gcloud

Terraform

应用更改

准备 Cloud Shell

准备目录

应用更改

删除更改

REST

修改截断行为

限制

使用 Cloud SQL Data API 执行 SQL 语句