使用写入端点连接到实例

概览

本页面介绍了如何使用写入端点，通过专用服务访问通道 (PSA) 从虚拟私有云 (VPC) 网络中的客户端连接到 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：
  • Compute Engine API
  • Cloud DNS API

  如果未在项目中启用 Cloud DNS API，则无法创建对等互连 DNS 区域，这会导致 DNS 名称无法使用。

  成功创建对等互连 DNS 区域后，请务必不要以任何方式修改该区域。任何修改（包括删除）都会导致 DNS 无法用于数据库连接。

• Cloud SQL 实例必须是 Cloud SQL 企业 Plus 版。
• Cloud SQL 实例必须配置为使用专用 IP，并启用专用服务访问通道 (PSA)。
• 此功能需要实例采用新网络架构。在大多数情况下，新实例是使用新架构创建的。如需验证这一点，请检查实例的网络架构。

如果您将现有的 Cloud SQL 企业版实例升级到 Cloud SQL 企业 Plus 版实例，并且满足前面列出的前提条件，Cloud SQL 会自动生成写入端点。如果现有实例采用的是旧网络架构，您必须先将实例升级到新网络架构，才能获取写入端点。

如果您已经有 Cloud SQL 企业 Plus 版实例，但该实例没有写入端点，并且您希望 Cloud SQL 自动生成写入端点，请创建启用了高级灾难恢复的副本。

查看写入端点

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

写入端点始终以 .global.sql-psa.goog. 后缀结尾，类似于以下示例：

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

如果对于符合条件的实例，您没有看到写入端点，请参阅问题排查。

使用写入端点连接到 Cloud SQL 实例

    psql -U DATABASE_NAME -h WRITE_ENDPOINT
  

通过 SSL/TLS 连接使用写入端点将数据库客户端与数据库实例连接

  psql "sslmode=SSL_MODE \
    sslrootcert=SSL_ROOT_SERVER \
    sslcert=SSL_CERT \
    sslkey=SSL_KEY \
    host=WRITE_ENDPOINT \
    port=PORT user=USERNAME \
    dbname=DATABASE_NAME"
  

使用 Cloud SQL Auth 代理或 Cloud SQL 语言连接器将数据库客户端连接到实例

当您使用写入端点 DNS 名称配置 Cloud SQL Auth 代理或某个 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 更新为指定的灾难恢复副本实例：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 代理会自动关闭与 my-project:region:instance-a 的所有现有连接。这会强制应用使用的任何连接池建立新连接。它还可能会导致正在进行的数据库查询失败。

Cloud SQL Auth 代理每 30 秒轮询一次 DNS 名称的更改。

更新实例网络配置

如果您的实例是在 2025 年 8 月 8 日之前创建的，您可能需要更新实例的网络配置，以便 Cloud SQL 语言连接器或 Cloud SQL Auth 代理能够使用写入端点。您只需为每个实例运行此更新任务一次。运行以下命令：

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

使用 Cloud SQL Auth 代理将数据库客户端连接到实例

如需通过写入端点并使用 Cloud SQL Auth 代理连接到 Cloud SQL 实例，请先使用写入端点（而非实例连接名称）启动代理

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT
  

  psql
    host=127.0.0.1 \
    port=PORT user=USERNAME \
    dbname=DATABASE_NAME"
  

使用 Cloud SQL 语言连接器进行连接

如需使用某个 Cloud SQL 语言连接器进行连接，请按照使用 Cloud SQL 语言连接器进行连接文档中的说明配置应用。然后，修改数据库连接，以使用写入端点而不是实例 DNS 名称。

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

    db, err := sql.Open(
        "cloudsql-postgres",
        "host=WRITE_ENDPOINT user=USERNAME password=PASSWORD dbname=DATABASE_NAME sslmode=disable",
    )
  

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

  import pg from 'pg';
  import {Connector} from '@google-cloud/cloud-sql-connector';
  const {Pool} = pg;

  const connector = new Connector();
  const clientOpts = await connector.getOptions({
    domainName: 'WRITE_ENDPOINT',
    ipType: 'PUBLIC',
  });
  const pool = new Pool({
    ...clientOpts,
    user: 'USERNAME',
    password: 'PASSWORD',
    database: 'DATABASE_NAME',
    max: 5,
  });
  

限制

• 写入端点不适用于 Cloud SQL 企业版实例创建。
• 写入端点不适用于仅限公共 IP 的实例或仅限 Private Service Connect 的实例。

问题排查

以下部分介绍了写入端点的架构，并说明了常见问题排查方法。

写入端点的架构

创建符合条件的实例时，系统会默认生成写入端点。

为了创建写入端点，Cloud SQL 会执行以下设置：

• 在服务 Cloud SQL 提供方 VPC 网络中创建专用 DNS 区域
• 在客户 VPC 网络中创建对等互连 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 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 使用方网络所在的项目的名称。

   如果存在带有 sql-psa.goog. 后缀的 DNS 区域，请在仔细检查以确认对等互连 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 beta sql instances patch 命令为符合条件的实例修复缺少写入端点这一问题：

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

   将 INSTANCE_NAME 替换为您的 Cloud SQL 实例的名称。

后续步骤

• 详细了解 Cloud SQL 问题排查。