Conectar-se a uma instância usando um endpoint de gravação

Visão geral

Nesta página, mostramos como usar um endpoint de gravação para se conectar de clientes na rede da nuvem privada virtual (VPC) a uma instância do Cloud SQL usando o Acesso a serviços particulares (PSA).

Um endpoint de gravação é um nome de serviço de nome de domínio (DNS) global que se refere ao endereço IP da instância principal atual automaticamente. No caso de uma operação de failover ou alternância de réplica, esse endpoint de gravação redireciona as conexões de entrada para a nova instância principal automaticamente. É possível usar o endpoint de gravação em uma string de conexão SQL à instância do Cloud SQL em vez de um endereço IP. Ao usar um endpoint de gravação, você evita ter que fazer mudanças na conexão do aplicativo ao realizar uma operação de failover ou alternância de réplica para recuperação de interrupção regional ou simulação de recuperação de desastres.

Cada instância do Cloud SQL qualificada tem um único endpoint de gravação integrado cujo nome, criação e atualização são gerenciados pelo Cloud SQL. O exemplo a seguir ilustra o formato dele:

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

O endpoint de gravação sempre termina com o sufixo .global.sql-psa.goog.. Não é possível modificar o nome ou o formato desse endpoint de gravação gerenciado pelo Cloud SQL.

É possível usar o endpoint de gravação para todas as operações de gravação na instância principal, incluindo inserções, atualizações, exclusões e mudanças de DDL. Também é possível usar o endpoint de gravação para operações de leitura, como consultas. O endereço IP particular apontado pelo endpoint de gravação é alterado automaticamente pelo Cloud SQL quando você realiza uma operação de failover ou alternância de réplica para promover uma instância de réplica como a nova instância principal.

Gerar o endpoint de gravação

Se você criar uma nova instância do Cloud SQL, o Cloud SQL vai criar o endpoint de gravação automaticamente quando os pré-requisitos a seguir forem atendidos:

• As APIs a seguir precisam estar ativadas no Cloud de Confiance projeto em que a instância do Cloud SQL reside:
  • API Compute Engine
  • API Cloud DNS

  Se você não ativar a API Cloud DNS no projeto, não será possível criar a zona de DNS de peering, o que tornará os nomes DNS inutilizáveis.

  Depois que a zona de DNS de peering for criada, é importante que ela não seja modificada de forma alguma. Qualquer modificação, incluindo a exclusão, vai tornar o DNS inutilizável para a conexão do banco de dados.

• A instância do Cloud SQL precisa ser da edição Cloud SQL Enterprise Plus.
• A instância do Cloud SQL precisa ser configurada para usar um IP particular com o Acesso a serviços particulares (PSA) ativado.
• O recurso exige instâncias na nova arquitetura de rede. Na maioria dos casos, novas instâncias são criadas com a nova arquitetura. Para verificar isso, confira a arquitetura de rede da sua instância.

Ao fazer upgrade de uma instância do Cloud SQL Enterprise para uma instância do Cloud SQL Enterprise Plus, o Cloud SQL gera automaticamente o endpoint de gravação se os pré-requisitos listados anteriormente forem atendidos. Se a instância atual estiver na arquitetura de rede antiga, primeiro faça upgrade da instância para a nova arquitetura de rede para receber o endpoint de gravação.

Se você já tiver uma instância do Cloud SQL Enterprise Plus sem o endpoint de gravação e quiser que o Cloud SQL gere um endpoint de gravação automaticamente, crie uma réplica ativada para recuperação avançada de desastres.

Conferir o endpoint de gravação

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

Os endpoints de gravação sempre terminam com o sufixo .global.sql-psa.goog., semelhante ao exemplo a seguir:

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

Se você não encontrar o endpoint de gravação para uma instância qualificada, consulte Solução de problemas.

Conectar-se a uma instância do Cloud SQL usando um endpoint de gravação

    psql -U DATABASE_NAME -h WRITE_ENDPOINT
  

Conectar clientes de banco de dados a instâncias de banco de dados usando o endpoint de gravação em uma conexão 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"
  

Conectar clientes de banco de dados a instâncias usando o proxy de autenticação do Cloud SQL ou os conectores de linguagem do Cloud SQL

Ao configurar o proxy de autenticação do Cloud SQL ou um dos conectores de linguagem do Cloud SQL usando um nome DNS de endpoint de gravação, o conector do Cloud SQL verifica periodicamente uma operação de alternância ou failover. Quando o conector do Cloud SQL detecta que o nome DNS do endpoint de gravação se refere a uma instância diferente, ele fecha todas as conexões abertas com a instância antiga. As tentativas de conexão subsequentes são direcionadas à nova instância.

Por exemplo, suponha que um aplicativo esteja configurado para se conectar usando o nome DNS do endpoint de gravação 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog. Inicialmente, a zona de DNS é configurada com um registro que aponta para a instância principal, my-project:region:instance-a. O aplicativo estabelece conexões com a instância do Cloud SQL my-project:region:instance-a.

Quando o failover ou a alternância ocorre, o Cloud SQL atualiza o registro DNS de my-project:region:instance-a para a instância de réplica de DR designada: my-project:other-region:instance-b.

O conector do Cloud SQL usado pelo aplicativo detecta a mudança nesse registro DNS. Quando o aplicativo se conecta ao banco de dados usando o nome DNS do endpoint de gravação 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog, ele se conecta à instância do Cloud SQL my-project:other-region:instance-b.

O conector ou o proxy de autenticação fecha automaticamente todas as conexões atuais com my-project:region:instance-a. Isso força todos os pools de conexão usados pelo aplicativo a estabelecer novas conexões. Também pode causar falha nas consultas de banco de dados em andamento.

O proxy de autenticação do Cloud SQL pesquisa mudanças no nome DNS a cada 30 segundos.

Atualizar a configuração de rede da instância

Se a instância foi criada antes de 8 de agosto de 2025, talvez seja necessário atualizar a configuração de rede da instância para que os conectores de linguagem do Cloud SQL ou o proxy de autenticação do Cloud SQL possam usar o endpoint de gravação. Só é necessário executar essa tarefa de atualização uma vez para cada instância. Execute este comando:

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

Conectar clientes de banco de dados a instâncias usando o proxy de autenticação do Cloud SQL

Para se conectar a uma instância do Cloud SQL pelo endpoint de gravação e usando o proxy de autenticação do Cloud SQL, primeiro inicie o proxy usando o endpoint de gravação em vez do nome de conexão da instância.

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT
  

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

Conectar usando os conectores de linguagem do Cloud SQL

Para se conectar usando um dos conectores de linguagem do Cloud SQL, configure o aplicativo seguindo as instruções na documentação Conectar usando os conectores de linguagem do Cloud SQL. Em seguida, modifique a conexão do banco de dados para usar o endpoint de gravação em vez do nome DNS da instância.

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

Limitações

• Os endpoints de gravação não estão disponíveis para criações de instâncias do Cloud SQL Enterprise.
• Os endpoints de gravação não estão disponíveis para instâncias somente de IP público ou somente do Private Service Connect.

Solução de problemas

As seções a seguir descrevem a arquitetura dos endpoints de gravação e abordam problemas comuns de solução de problemas.

Arquitetura de um endpoint de gravação

Quando você cria uma instância qualificada, um endpoint de gravação é gerado por padrão.

Para criar um endpoint de gravação, o Cloud SQL realiza a seguinte configuração:

• Cria uma zona de DNS particular na rede VPC do produtor de serviços do Cloud SQL
• Cria uma zona de DNS de peering na rede VPC do cliente
• Cria um registro DNS na zona de DNS particular na rede do produtor de serviços

O diagrama a seguir ilustra como esse processo funciona:

Problemas de resolução de DNS

Se a resolução de DNS não estiver funcionando, verifique cada um dos itens a seguir:

1. Verifique se todos os pré-requisitos foram atendidos.
2. Verifique se os clientes em que a resolução é esperada estão localizados em na mesma rede a que a instância do Cloud SQL está anexada. Para verificar isso, use o gcloud compute instances list comando:

   gcloud compute instances list \
      --format="table( name, zone.basename(), networkInterfaces[].network )" \
      --project=PROJECT_NAME

   Substitua PROJECT_NAME pelo nome do projeto em que a rede de consumidor de DNS reside.

3. Verifique se a zona de peering existe. Para fazer isso, use o gcloud dns managed-zones list comando:

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

   Substitua PROJECT_NAME pelo nome do projeto em que a rede de consumidor de DNS reside.

4. Se a zona de peering não existir, você poderá corrigir o problema usando o gcloud sql instances patch comando:

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

   Substitua INSTANCE_NAME pelo nome da instância do Cloud SQL.

A nova instância não tem um endpoint de gravação

Se uma instância recém-criada não contiver um endpoint de gravação, verifique cada um dos itens a seguir:

1. Verifique se todos os pré-requisitos foram concluídos.
2. Verifique se não há uma zona de DNS de peering restante com o nome DNS sql-psa.goog..

   Uma zona de DNS de peering é uma zona de DNS restante se a rede associada com a zona de DNS não tiver um peering de VPC com o ID do projeto de peering da zona de DNS de peering.

   Se houver uma zona de DNS de peering restante com o sql-psa.goog. sufixo, exclua-a.

   Para verificar se há zonas de DNS de peering restantes, use o gcloud dns managed-zones list comando:

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

   Substitua PROJECT_NAME pelo nome do projeto em que a rede de consumidor de DNS reside.

   Se uma zona de DNS existir com o sufixo sql-psa.goog., exclua a zona de DNS depois de verificar se a zona de DNS de peering é uma zona de DNS restante.

   Para excluir uma zona de DNS, use o comando gcloud dns managed-zones delete:

   gcloud dns managed-zones delete ZONE_NAME

   Substitua ZONE_NAME pelo nome da zona de DNS associada aos endpoints de gravação. Os valores são alfanuméricos e usam o seguinte formato: cloud-sql-psa-dns-1234567890.

3. É possível corrigir um endpoint de gravação ausente para uma instância qualificada usando o comando gcloud beta sql instances patch:

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

   Substitua INSTANCE_NAME pelo nome da instância do Cloud SQL.

A seguir

• Saiba mais sobre a solução de problemas do Cloud SQL.