Associe-se a uma instância através de um ponto final de gravação

Vista geral

Esta página mostra como usar um ponto final de gravação para estabelecer ligação a partir de clientes na sua rede de nuvem privada virtual (VPC) a uma instância do Cloud SQL através do acesso privado a serviços (PSA).

Um ponto final de gravação é um nome de serviço de nomes de domínio (DNS) global que é resolvido automaticamente para o endereço IP da instância principal atual. No caso de uma operação de comutação por falha ou comutação de uma réplica, este ponto final de gravação redireciona automaticamente as ligações recebidas para a nova instância principal. Pode usar o ponto final de gravação numa string de ligação SQL à instância do Cloud SQL em vez de usar um endereço IP. Ao usar um ponto final de gravação, pode evitar ter de fazer alterações à ligação da aplicação quando executa uma operação de comutação por falha ou comutação para recuperação de falhas de região ou simulação de recuperação de desastres.

Cada instância do Cloud SQL elegível tem um único ponto final de gravação incorporado cujo nome, criação e atualização são geridos pelo Cloud SQL. O exemplo seguinte ilustra o formato:

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

O ponto final de gravação termina sempre com o sufixo .global.sql-psa.goog.. Não pode modificar o nome nem o formato deste ponto final de gravação gerido pelo Cloud SQL.

Pode usar o ponto final de gravação para todas as operações de gravação na instância principal, incluindo inserções, atualizações, eliminações e alterações de DDL. Também pode usar o endpoint write para operações de leitura, como consultas. O endereço IP privado apontado pelo ponto final de gravação é alterado automaticamente pelo Cloud SQL quando executa uma operação de comutação por falha ou comutação de réplica para promover uma instância de réplica como a nova instância principal.

Gere o ponto final de escrita

Se criar uma nova instância do Cloud SQL, o Cloud SQL cria automaticamente o ponto final de gravação quando os seguintes pré-requisitos são cumpridos:

• As seguintes APIs têm de estar ativadas no Trusted Cloud projeto onde reside a sua instância do Cloud SQL:
  • API Compute Engine
  • Cloud DNS API

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

  Depois de criar com êxito a zona DNS de peering, é importante que não seja modificada de forma alguma. Quaisquer modificações, incluindo a eliminação, tornam o DNS inutilizável para a ligação à base de dados.

• A instância do Cloud SQL tem de ser a edição Cloud SQL Enterprise Plus.
• A instância do Cloud SQL tem de estar configurada para usar um IP privado com o acesso privado a serviços (APS) ativado.
• A funcionalidade requer instâncias na nova arquitetura de rede. Na maioria dos casos, as novas instâncias são criadas com a nova arquitetura. Para validar esta situação, verifique a arquitetura de rede da sua instância.

Quando atualiza uma instância da edição Cloud SQL Enterprise existente para uma instância da edição Cloud SQL Enterprise Plus, o Cloud SQL gera automaticamente o ponto final de gravação se os pré-requisitos indicados anteriormente forem cumpridos. Se a sua instância existente estiver na arquitetura de rede antiga, primeiro tem de atualizar a instância para a nova arquitetura de rede para obter o ponto final de gravação.

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

Veja o ponto final de gravação

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

Os pontos finais de escrita terminam sempre com o sufixo .global.sql-psa.goog., semelhante ao seguinte exemplo:

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

Se não vir o ponto final de gravação para uma instância elegível, consulte a secção Resolução de problemas.

Associe-se a uma instância do Cloud SQL através de um ponto final de gravação

    mysql -u root -h WRITE_ENDPOINT -p
  

Ligue clientes de bases de dados a instâncias de bases de dados através do ponto final de gravação numa ligação 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
  

Ligue clientes de bases de dados a instâncias através do proxy Auth do Cloud SQL ou dos conetores de linguagem do Cloud SQL

Quando configura o proxy Auth do Cloud SQL ou um dos conetores de linguagem do Cloud SQL através de um nome DNS do ponto final de gravação, o conetor do Cloud SQL verifica periodicamente se existe uma operação de mudança ou failover. Quando o conetor do Cloud SQL deteta que o nome DNS do ponto final de gravação se refere a uma instância diferente, fecha todas as ligações abertas à instância antiga. As tentativas de ligação subsequentes são direcionadas para a nova instância.

Por exemplo, suponhamos que uma aplicação está configurada para estabelecer ligação através do nome DNS do ponto final de gravação 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog. Inicialmente, a zona DNS é configurada com um registo que aponta para a instância principal, my-project:region:instance-a. A aplicação estabelece ligações à instância do my-project:region:instance-aCloud SQL.

Quando ocorre a comutação por falha ou a comutação, o Cloud SQL atualiza o registo de DNS de my-project:region:instance-a para a instância de réplica de recuperação de desastres designada: my-project:other-region:instance-b.

O conetor do Cloud SQL usado pela aplicação deteta a alteração a este registo DNS. Quando a aplicação se liga à respetiva base de dados através do nome DNS do ponto final de gravação103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog, liga-se à instância do Cloud SQLmy-project:other-region:instance-b.

O conector ou o proxy de autenticação fecha automaticamente todas as ligações existentes a my-project:region:instance-a. Isto força todos os conjuntos de ligações usados pela aplicação a estabelecerem novas ligações. Também pode fazer com que as consultas de base de dados em curso falhem.

O proxy Auth do Cloud SQL procura alterações ao nome DNS a cada 30 segundos.

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

Se a sua instância foi criada antes de 8 de agosto de 2025, pode ter de 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 ponto final de gravação. Só tem de executar esta tarefa de atualização uma vez para cada instância. Execute o seguinte comando:

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

Ligue clientes de bases de dados a instâncias através do proxy Auth do Cloud SQL

Para se ligar a uma instância do Cloud SQL através do respetivo ponto final de gravação e usando o proxy Auth do Cloud SQL, primeiro inicie o proxy através do ponto final de gravação em vez do nome de ligação da instância

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT
  

  mysql -uUSERNAME -h 127.0.0.1 -p PORT DATABASE_NAME
  

Estabeleça ligação através dos conectores de linguagem do Cloud SQL

Para estabelecer ligação através de um dos conetores de linguagem do Cloud SQL, configure a sua aplicação seguindo as instruções na documentação de ligação através de conetores de linguagem do Cloud SQL. Em seguida, modifique a ligação à base de dados para usar o ponto final de gravação em vez do nome DNS da instância.

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

Limitações

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

Resolução de problemas

As secções seguintes descrevem a arquitetura dos pontos finais de gravação e abordam problemas comuns de resolução.

Arquitetura de um ponto final de gravação

Quando cria uma instância elegível, é gerado um ponto final de gravação por predefinição.

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

• Cria uma zona DNS privada na rede VPC do produtor do Cloud SQL
• Cria uma zona DNS de intercâmbio na rede VPC do cliente
• Cria um registo de DNS na zona de DNS privado na rede do produtor de serviços

O diagrama seguinte ilustra como funciona este processo:

Problemas de resoluções de DNS

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

1. Certifique-se de que todos os pré-requisitos são cumpridos.
2. Certifique-se de que os clientes onde a resolução é esperada estão localizados na mesma rede à qual a instância do Cloud SQL está anexada. Para verificar isto, use o comando gcloud compute instances list:

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

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

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

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

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

4. Se a zona de peering não existir, pode corrigir o problema através do comando gcloud beta sql instances patch:

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

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

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

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

1. Certifique-se de que todos os pré-requisitos estão concluídos.
2. Certifique-se de que não existe uma zona DNS de peering remanescente com o nome DNS sql-psa.goog..

   Uma zona DNS de intercâmbio é uma zona DNS remanescente se a rede associada à zona DNS não tiver um intercâmbio das redes da VPC com o ID do projeto de intercâmbio da zona DNS de intercâmbio.

   Se existir uma zona de DNS de peering remanescente com o sufixo sql-psa.goog., elimine-a.

   Para verificar se existem zonas de DNS de peering residuais, use o comando: gcloud dns managed-zones list

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

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

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

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

   gcloud dns managed-zones delete ZONE_NAME

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

3. Pode corrigir um ponto final de escrita em falta para uma instância elegível através do comando gcloud beta sql instances patch:

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

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

O que se segue?

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