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

本頁說明如何使用 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 陳述式，請先完成下列步驟：

必要角色或權限

根據預設，具備下列任一角色的使用者或服務帳戶，都有權在 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。

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=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 陳述式。如果陳述式含有空格或殼層特殊字元，就必須加上引號。
  • PARTIAL_RESULT_MODE：選用。控管結果不完整時的回應方式。可以是 ALLOW_PARTIAL_RESULT、FAIL_PARTIAL_RESULT 或 PARTIAL_RESULT_MODE_UNSPECIFIED。請參閱「修改截斷行為」。

如有需要，您也可以加上 --project=PROJECT_ID 旗標。

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"
}

請將下列項目改為對應的值：

  • 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 個。如果達到這個上限，後續要求就會失敗，並顯示「Maximum concurrent reads 10 reached」(已達到並行讀取作業數上限 10)。
  • 每個回應最多可包含 10 則資料庫訊息或警告。
  • 如果陳述式語法或執行階段發生錯誤，系統就不會傳回任何結果。
  • 如果陳述式耗用大量記憶體，可能會導致記憶體不足錯誤。如要進一步瞭解如何避免發生這些錯誤，請參閱「管理記憶體用量的最佳做法」。如果資料庫執行個體的記憶體用量偏高，通常會導致效能問題、停滯，甚至資料庫停機。