使用 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 擴充功能。

事前準備

如要在執行個體上執行 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)

您也可以為使用者或服務帳戶定義 IAM 自訂角色，其中包含 cloudsql.instances.executesql 權限。這項權限支援身分與存取權管理自訂角色。

啟用或停用 Data API

如要使用 Google Data API，必須為每個執行個體啟用這項功能。您隨時可以停用 Data API。

控制台

前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

前往 Cloud SQL 執行個體
如要開啟執行個體的「總覽」頁面，請按一下執行個體名稱。
在 SQL 導覽選單中，選取「連線」。
按一下 [網路] 分頁標籤。
勾選「允許 Data API」核取方塊。
按一下 [儲存]。

gcloud

如要在執行個體上啟用 Data API 存取權，請使用 gcloud sql instances patch 指令並加上 --data-api-access=ALLOW_DATA_API 標記：

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

如要停用 Google 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 陳述式。如果陳述式含有空格或殼層特殊字元，就必須加上引號。
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 顯示「Apply complete!」訊息。
開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

刪除變更

刪除 google_sql_provision_script 資源不會刪除該資源在資料庫中建立的資源。如要刪除這些項目，您可以在指令碼中明確新增 drop ... if exists 等陳述式，然後套用變更。

REST

如要使用 REST API 對執行個體上的資料庫執行 SQL 陳述式，請將 POST 要求傳送至 executeSql 端點：

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。
您只能為正在執行的 PostgreSQL 適用的 Cloud SQL 執行個體執行 SQL 陳述式。
如果執行個體已設定為外部伺服器複製，Cloud SQL 就不支援搭配使用 Data API。
如果要求超過 30 秒未完成，系統就會取消要求。系統不支援使用 SET STATEMENT_TIMEOUT 設定較高的陳述式逾時時間。
Cloud SQL 會限制每位使用者對每個執行個體發出的並行 executeSql 要求數量，上限為 10 個。如果達到上限，後續要求會失敗，並顯示「At most 10 concurrent queries may be run on this instance. 請稍後再試。」或「並行讀取次數已達上限 (10 次)。」
每個回應最多可包含 10 則資料庫訊息或警告。
如果陳述式語法或執行階段發生錯誤，系統就不會傳回任何結果。
如果陳述式耗用大量記憶體，可能會導致記憶體不足錯誤。如要進一步瞭解如何避免發生這些錯誤，請參閱「管理記憶體用量的最佳做法」。如果資料庫執行個體的記憶體用量偏高，通常會導致效能問題、停滯，甚至資料庫停機。
如果執行個體正在進行特定維護作業，為確保資料完整性，資料 API 可能會暫時遭到封鎖。如果發生這種情況，請稍後再試。
Data API 目前不保證資料落地。對於特定 Assured Workloads 專案，以及手動強制執行的專案，要求會失敗並顯示「not supported for instances in certain Assured Workloads control packages folders」錯誤。constraints/sql.restrictNoncompliantResourceCreation

使用 Cloud SQL Data API 執行 SQL 陳述式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要角色或權限

啟用或停用 Data API

控制台

gcloud

執行 SQL 陳述式

gcloud

Terraform

套用變更

準備 Cloud Shell

準備目錄

套用變更

刪除變更

REST

修改截斷行為

限制

使用 Cloud SQL Data API 執行 SQL 陳述式