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

總覽

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

寫入端點是全域網域名稱服務 (DNS) 名稱，會自動解析為目前主要執行個體的 IP 位址。如果副本進行容錯移轉或切換作業，這個寫入端點會自動將傳入連線重新導向至新的主要執行個體。您可以在 Cloud SQL 執行個體的 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 執行個體所在的 Cloud de Confiance 專案中，必須啟用下列 API：
  • Compute Engine API
  • Cloud DNS 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 sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

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

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

如果找不到符合資格執行個體的寫入端點，請參閱「疑難排解」一節。

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

    mysql -u root -h WRITE_ENDPOINT -p
  

透過 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
  

使用 Cloud SQL Auth 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 的記錄。應用程式會建立與 my-project:region:instance-a Cloud SQL 執行個體的連線。

發生容錯移轉或切換時，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 Auth Proxy 每 30 秒會輪詢一次 DNS 名稱變更。

更新執行個體網路設定

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

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

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

如要透過寫入端點和 Cloud SQL Auth Proxy 連線至 Cloud SQL 執行個體，請先使用寫入端點 (而非執行個體連線名稱) 啟動 Proxy。

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT
  

  mysql -uUSERNAME -h 127.0.0.1 -p PORT DATABASE_NAME
  

使用 Cloud SQL 語言連接器連線

如要使用 Cloud SQL 語言連接器連線，請按照使用 Cloud SQL 語言連接器連線說明文件中的指示設定應用程式。接著，修改資料庫連線，改用寫入端點，而非執行個體 DNS 名稱。

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

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

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

  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',
  });
  

限制

• 建立 Cloud SQL Enterprise 版本執行個體時，無法使用寫入端點。
• 寫入端點不適用於僅限公開 IP 的執行個體，或僅限 Private Service Connect 的執行個體。

疑難排解

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

寫入端點的架構

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

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

• 在服務 Cloud SQL 供應商虛擬私有雲網路中建立私人 DNS 區域
• 在客戶虛擬私有雲網路中建立對接 DNS 區域
• 在服務生產者網路的私人 DNS 區域中建立 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 sql instances patch 指令修正問題：

   gcloud sql instances patch INSTANCE_NAME --reconcile-psa-networking

   將 INSTANCE_NAME 替換為 Cloud SQL 執行個體名稱。

新執行個體沒有寫入端點

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

1. 確認已完成所有必要條件。
2. 確認沒有 DNS 名稱為 sql-psa.goog. 的對接 DNS 區域。

   如果與 DNS 區域相關聯的網路，未與對接 DNS 區域的對接專案 ID 建立虛擬私有雲對接，則該對接 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 區域。

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

   gcloud dns managed-zones delete ZONE_NAME

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

3. 您可以使用 gcloud sql instances patch 指令，為符合資格的執行個體修正缺少的寫入端點：

   gcloud sql instances patch INSTANCE_NAME --reconcile-psa-networking

   將 INSTANCE_NAME 替換為 Cloud SQL 執行個體名稱。

後續步驟

• 進一步瞭解 Cloud SQL 疑難排解。