使用寫入端點連線至執行個體

總覽

本頁說明如何使用寫入端點，從虛擬私有雲 (VPC) 網路中的用戶端，透過私人服務存取權 (PSA) 連線至 Cloud SQL 執行個體。

寫入端點是全域網域名稱服務 (DNS) 名稱，會自動解析為目前主要執行個體的 IP 位址。如果發生備用資源容錯移轉或切換作業，這個寫入端點會自動將連入連線重新導向至新的主要執行個體。您可以在 SQL 連線字串中使用寫入端點，連線至 Cloud SQL 執行個體，而不必使用 IP 位址。使用寫入端點，您就不必在執行副本容錯移轉或切換作業時變更應用程式連線，以進行區域中斷復原或災害復原演練。

每個符合資格的 Cloud SQL 執行個體都有單一內建寫入端點，其名稱、建立和更新作業皆由 Cloud SQL 管理。以下範例說明其格式：

  103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.

寫入端點一律以 .global.sql-psa.goog. 後置字元結尾。 您無法修改 Cloud SQL 管理的寫入端點名稱或格式。

您可以在主要執行個體上使用寫入端點執行所有寫入作業，包括插入、更新、刪除和 DDL 變更。您也可以使用寫入端點進行讀取作業，例如查詢。當您執行副本容錯移轉或切換作業，將副本執行個體升級為新的主要執行個體時，Cloud SQL 會自動變更寫入端點指向的私人 IP 位址。

產生寫入端點

如果您建立新的 Cloud SQL 執行個體，Cloud SQL 會在符合下列必要條件時，自動建立寫入端點：

  • 您必須在 Cloud SQL 執行個體所在的 Google Cloud 專案中啟用下列 API：

    如果未在專案中啟用 Cloud DNS API，就無法建立對等互連 DNS 區域，導致 DNS 名稱無法使用。

    對等互連 DNS 可用區建立完成後，請勿以任何方式修改。任何修改 (包括刪除) 都會導致 DNS 無法用於資料庫連線。

  • Cloud SQL 執行個體必須是 Cloud SQL Enterprise Plus 版本。
  • Cloud SQL 執行個體必須設定為使用私人 IP，並啟用私人服務存取權 (PSA)。
  • 這項功能需要使用新網路架構的執行個體。在大多數情況下，新執行個體會採用新架構。如要確認這一點，請檢查執行個體的網路架構。

將現有的 Cloud SQL Enterprise 版執行個體升級為 Cloud SQL Enterprise Plus 版執行個體時，如果符合先前列出的必要條件，Cloud SQL 會自動產生寫入端點。如果現有執行個體採用舊版網路架構，您必須先將執行個體升級為新版網路架構，才能取得寫入端點。

如果您已有 Cloud SQL Enterprise Plus 版本執行個體，但沒有寫入端點，且希望 Cloud SQL 自動產生寫入端點，請建立已啟用進階災難復原功能的副本。

查看寫入端點

gcloud

如要找出寫入端點，請使用下列 gcloud CLI 指令：

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint

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

：Cloud SQL 執行個體的名稱。INSTANCE_NAME

寫入端點一律會以 .global.sql-psa.goog. 字尾結尾，類似以下範例：

  103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.

如果沒有看到符合資格的執行個體寫入端點，請參閱「疑難排解」。

使用寫入端點連線至 Cloud SQL 執行個體

mysql

如要使用寫入端點將 mysql 用戶端連線至 Cloud SQL 執行個體，請執行下列指令：

    mysql -u root -h WRITE_ENDPOINT -p

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

WRITE_ENDPOINT：DNS 名稱或寫入端點。這個英數字元值一律會以 .global.sql-psa.goog. 字尾結尾。例如：103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.。

透過 SSL/TLS 連線，使用寫入端點將資料庫用戶端連線至資料庫執行個體

mysql

如要透過 SSL/TLS 連線，使用寫入端點將資料庫用戶端連線至執行個體，請執行下列指令：

  mysql -uroot -pcloudsql -h 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog. \
    --ssl-ca=SERVER_CA_SSL \
    --ssl-cert=SSL_CERT \
    --ssl-key=SSL_KEY \
    --ssl-verify-server-cert

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

  • SERVER_CA_SSL：伺服器憑證授權單位 SSL 檔案的名稱。例如：server-ca.pem。
  • SSL_CERT：用戶端 SSL 憑證的名稱。例如：client-cert.pem。
  • SSL_KEY：用戶端 SSL 金鑰的名稱。例如：client-key.pem。

使用 Cloud SQL 驗證 Proxy 或 Cloud SQL 語言連接器，將資料庫用戶端連線至執行個體

使用寫入端點 DNS 名稱設定 Cloud SQL Auth Proxy 或其中一個 Cloud SQL 語言連接器時，Cloud SQL 連接器會定期檢查切換或容錯移轉作業。Cloud SQL 連接器偵測到寫入端點 DNS 名稱參照其他執行個體時，會關閉與舊執行個體的所有開啟連線。後續連線嘗試會導向新執行個體。

舉例來說，假設應用程式已設定為使用寫入端點 DNS 名稱 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog 連線。一開始，DNS 區域會設定指向主要執行個體的記錄，my-project:region:instance-a。應用程式會建立與 Cloud SQL 執行個體的連線。my-project:region:instance-a

發生容錯移轉或切換時，Cloud SQL 會將 DNS 記錄從 my-project:region:instance-a 更新為指定的 DR 備用資源執行個體：my-project:other-region:instance-b。

應用程式使用的 Cloud SQL 連接器會偵測到這項 DNS 記錄變更。應用程式使用寫入端點 DNS 名稱 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog 連線至資料庫時，會連線至 my-project:other-region:instance-b Cloud SQL 執行個體。

連接器或 Auth Proxy 會自動關閉與 my-project:region:instance-a 的所有現有連線。這會強制應用程式使用的任何連線集區建立新連線。也可能導致進行中的資料庫查詢失敗。

Cloud SQL 驗證 Proxy 每 30 秒會輪詢 DNS 名稱的變更。

更新執行個體網路設定

如果執行個體是在 2025 年 8 月 8 日前建立，您可能需要更新執行個體的網路設定，Cloud SQL 語言連接器或 Cloud SQL Auth Proxy 才能使用寫入端點。每個執行個體只需要執行一次這項更新工作。執行下列指令：

gcloud CLI

  # Update the primary instance DNS settings
  gcloud \
      alpha sql instances patch "PRIMARY_NAME" \
      --reconcile-psa-networking

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

  • PRIMARY_NAME：執行個體的名稱。例如：my-instance

使用 Cloud SQL 驗證 Proxy 將資料庫用戶端連線至執行個體

如要透過寫入端點連線至 Cloud SQL 執行個體，並使用 Cloud SQL 驗證 Proxy，請先使用寫入端點啟動 Proxy，而非執行個體連線名稱

mysql

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT

然後設定資料庫用戶端，連線至 Cloud SQL 驗證 Proxy：

  mysql -uUSERNAME -h 127.0.0.1 -p PORT DATABASE_NAME

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

  • WRITE_ENDPOINT：DNS 名稱或寫入端點。這個英數字元值一律會以 .global.sql-psa.goog. 字尾結尾。例如：103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.。
  • PORT：Proxy 用來監聽連線的通訊埠號碼。例如：3306。
  • USERNAME：MySQL 使用者名稱。例如：root。
  • DATABASE_NAME：資料庫名稱。例如：mysql。

使用 Cloud SQL 語言連接器連線

如要使用其中一個 Cloud SQL 語言連接器連線，請按照「使用 Cloud SQL 語言連接器連線」一文中的操作說明設定應用程式。然後，修改資料庫連線，改用寫入端點，而非執行個體 DNS 名稱。

Java

  String jdbcUrl = "jdbc:mysql://WRITE_ENDPOINT/DATABASE_NAME?"
    +   "&socketFactory=com.google.cloud.sql.mysql.SocketFactory"
    +   "&user=USERNAME"
    +   "&password=PASSWORD";

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

  • WRITE_ENDPOINT：DNS 名稱或寫入端點。這個英數字元值一律會以 .global.sql-psa.goog. 字尾結尾。
  • DATABASE_NAME：資料庫名稱。例如：my-database。
  • USERNAME：使用者名稱。例如：postgres。
  • PASSWORD：資料庫密碼。
詳情請參閱 GitHub 上的 Java 連接器說明文件。

Go

    db, err := sql.Open(
        "cloudsql-mysql",
        "USERNAME:PASSWORD@cloudsql-mysql(WRITE_ENDPOINT)/DATABASE_NAME",
    )

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

  • WRITE_ENDPOINT：DNS 名稱或寫入端點。這個英數字元值一律會以 .global.sql-psa.goog. 字尾結尾。
  • DATABASE_NAME：資料庫名稱。例如：my-database。
  • USERNAME：使用者名稱。例如：postgres。
  • PASSWORD：資料庫密碼。
詳情請參閱 GitHub 上的 Go 連接器說明文件。

Python

  pool = sqlalchemy.create_engine(
      "mysql+pymysql://",
      creator=lambda: connector.connect(
          "WRITE_ENDPOINT",  # using DNS name
          "pymysql",
          user="USERNAME",
          password="PASSWORD",
          db="DATABASE_NAME"
      ),
  )

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

  • WRITE_ENDPOINT：DNS 名稱或寫入端點。這個英數字元值一律會以 .global.sql-psa.goog. 字尾結尾。
  • DATABASE_NAME：資料庫名稱。例如：my-database。
  • USERNAME：使用者名稱。例如：postgres。
  • PASSWORD：資料庫密碼。
詳情請參閱 GitHub 上的 Python 連接器文件。

Node.js

  import mysql from 'mysql2/promise';
  import {Connector} from '@google-cloud/cloud-sql-connector';

  const connector = new Connector();
  const clientOpts = await connector.getOptions({
    domainName: 'WRITE_ENDPOINT',
    ipType: 'PUBLIC',
  });

  const pool = await mysql.createPool({
    ...clientOpts,
    user: 'USERNAME',
    password: 'PASSWORD',
    database: 'DATABASE_NAME',
  });

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

  • WRITE_ENDPOINT：DNS 名稱或寫入端點。這個英數字元值一律會以 .global.sql-psa.goog. 字尾結尾。
  • DATABASE_NAME：資料庫名稱。例如：my-database。
  • USERNAME：使用者名稱。例如：postgres。
  • PASSWORD：資料庫密碼。
詳情請參閱 GitHub 上的 Node.js 連接器說明文件。

限制

  • Cloud SQL Enterprise 版執行個體建立作業不支援寫入端點。
  • 寫入端點不適用於僅限公開 IP 或僅限 Private Service Connect 的執行個體。

疑難排解

以下各節說明寫入端點的架構，並解決常見的疑難排解問題。

寫入端點的架構

建立符合資格的執行個體時，系統會預設產生寫入端點。

如要建立寫入端點，Cloud SQL 會執行下列設定：

下圖說明這個程序的運作方式：

圖表：顯示虛擬私有雲對等互連如何支援專案之間的 DNS 區域對等互連。
圖 1. 這張圖表顯示虛擬私有雲對等互連如何支援服務供應商網路與客戶網路之間的 DNS 區域對等互連。

DNS 解析問題

如果 DNS 解析無法正常運作，請檢查下列各個項目：

  1. 確認符合所有必要條件。
  2. 請確認預期會解析的用戶端位於與 Cloud SQL 執行個體連結的相同網路。如要檢查，請使用 gcloud compute instances list 指令：
    gcloud compute instances list \
   --format="table( name, zone.basename(), networkInterfaces[].network )" \
   --project=PROJECT_NAME

    將 PROJECT_NAME 替換為 DNS 消費者網路所在的專案名稱。

  3. 確認對等互連區域是否存在。做法是使用以下 gcloud dns managed-zones list 指令：
    gcloud dns managed-zones list \
    --project=PROJECT_NAME

    將 PROJECT_NAME 替換為 DNS 消費者網路所在的專案名稱。

  4. 如果對等互連區域不存在，可以使用 gcloud beta sql instances patch 指令修正問題：
    gcloud beta sql instances patch INSTANCE_NAME --reconcile-psa-networking

    將 INSTANCE_NAME 改成 Cloud SQL 執行個體的名稱。

新例項沒有寫入端點

如果新建立的執行個體不含寫入端點，請檢查下列各個項目：

  1. 請確認已完成所有必要條件。
  2. 確認沒有 DNS 名稱為「sql-psa.goog.」的剩餘對等互連 DNS 區域。

    如果與 DNS 區域相關聯的網路，與對等互連 DNS 區域的對等互連專案 ID 沒有 VPC 對等互連，則對等互連 DNS 區域就是遺留的 DNS 區域。

    如果還有以 sql-psa.goog. 字尾結尾的對等互連 DNS 區域，請刪除。

    如要檢查是否有剩餘的對等互連 DNS 區域，請使用 gcloud dns managed-zones list 指令：

    gcloud dns managed-zones list \
   --project=PROJECT_NAME

    將 PROJECT_NAME 替換為 DNS 消費者網路所在的專案名稱。

    如果 DNS 區域的後置字串為 sql-psa.goog.，請仔細檢查確認該 DNS 區域是遺留的 DNS 區域，然後刪除。

    如要刪除 DNS 區域，請使用 gcloud dns managed-zones delete 指令：

    gcloud dns managed-zones delete ZONE_NAME

    將 ZONE_NAME 替換為與寫入端點相關聯的 DNS 區域名稱。值為英數字元，格式如下： cloud-sql-psa-dns-1234567890。

  3. 如要修正符合資格的執行個體缺少寫入端點的問題，請使用 gcloud beta sql instances patch 指令：
    gcloud beta sql instances patch INSTANCE_NAME --reconcile-psa-networking

    將 INSTANCE_NAME 改成 Cloud SQL 執行個體的名稱。

後續步驟