Connettersi a un'istanza utilizzando un endpoint di scrittura

MySQL   |  PostgreSQL   |  SQL Server

Panoramica

Questa pagina mostra come utilizzare un endpoint di scrittura per connetterti dai client nella rete Virtual Private Cloud (VPC) a un'istanza Cloud SQL utilizzando l'accesso privato ai servizi (PSA).

Un endpoint di scrittura è un nome del servizio di nomi di dominio (DNS) globale che si risolve automaticamente nell'indirizzo IP dell'istanza principale attuale. In caso di operazione di failover o switchover della replica, questo endpoint di scrittura reindirizza automaticamente le connessioni in entrata alla nuova istanza principale. Puoi utilizzare l'endpoint di scrittura in una stringa di connessione SQL all'istanza Cloud SQL anziché utilizzare un indirizzo IP. Utilizzando un endpoint di scrittura, puoi evitare di dover apportare modifiche alla connessione dell'applicazione quando esegui un'operazione di failover o switchover della replica per il ripristino in caso di interruzione della regione o per un'esercitazione di ripristino di emergenza.

Ogni istanza Cloud SQL idonea ha un singolo endpoint di scrittura integrato il cui nome, creazione e aggiornamento sono gestiti da Cloud SQL. L'esempio seguente illustra il formato:

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

L'endpoint di scrittura termina sempre con il suffisso .global.sql-psa.goog.. Non puoi modificare il nome o il formato di questo endpoint di scrittura gestito da Cloud SQL.

Puoi utilizzare l'endpoint di scrittura per tutte le operazioni di scrittura sull'istanza principale, inclusi inserimenti, aggiornamenti, eliminazioni e modifiche DDL. Puoi anche utilizzare l'endpoint di scrittura per le operazioni di lettura, ad esempio le query. L'indirizzo IP privato a cui punta l'endpoint di scrittura viene modificato automaticamente da Cloud SQL quando esegui un'operazione di failover o switchover della replica per promuovere un'istanza replica come nuova istanza principale.

Genera l'endpoint di scrittura

Se crei una nuova istanza Cloud SQL, Cloud SQL crea automaticamente l'endpoint di scrittura quando vengono soddisfatti i seguenti prerequisiti:

• Le seguenti API devono essere abilitate nel Google Cloud progetto in cui si trova l'istanza Cloud SQL:
  • API Compute Engine
  • API Cloud DNS

  Se non abiliti l'API Cloud DNS nel progetto, non viene creata la zona DNS di peering, il che renderà inutilizzabili i nomi DNS.

  Una volta creata correttamente la zona DNS di peering, è importante che non venga modificata in alcun modo. Qualsiasi modifica, inclusa l'eliminazione, renderà inutilizzabile il DNS per la connessione al database.

• L'istanza Cloud SQL deve essere la versione Cloud SQL Enterprise Plus.
• L'istanza Cloud SQL deve essere configurata per utilizzare un IP privato con l'accesso privato ai servizi (PSA) abilitato.
• La funzionalità richiede istanze sulla nuova architettura di rete. Nella maggior parte dei casi, le nuove istanze vengono create con la nuova architettura. Per verificarlo, controlla l'architettura di rete dell'istanza.

Quando esegui l'upgrade di un'istanza Cloud SQL Enterprise esistente a un'istanza Cloud SQL Enterprise Plus, Cloud SQL genera automaticamente l'endpoint di scrittura se vengono soddisfatti i prerequisiti elencati in precedenza. Se l'istanza esistente si trova nella vecchia architettura di rete, devi prima eseguire l'upgrade dell'istanza alla nuova architettura di rete per ottenere l'endpoint di scrittura.

Se hai già un'istanza Cloud SQL Enterprise Plus senza l'endpoint di scrittura e vuoi che Cloud SQL generi automaticamente un endpoint di scrittura, crea una replica abilitata per il disaster recovery avanzato.

Visualizza l'endpoint di scrittura

gcloud

Per trovare l'endpoint di scrittura, utilizza il seguente comando gcloud CLI:

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

Esegui le seguenti sostituzioni:

INSTANCE_NAME: il nome dell'istanza Cloud SQL.

Gli endpoint di scrittura terminano sempre con il suffisso .global.sql-psa.goog., come nel seguente esempio:

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

Se non vedi l'endpoint di scrittura per un'istanza idonea, consulta la sezione Risoluzione dei problemi.

Connettiti a un'istanza Cloud SQL utilizzando un endpoint di scrittura

psql

Per connettere un client psql a un'istanza Cloud SQL utilizzando l'endpoint di scrittura, esegui il seguente comando:

    psql -U DATABASE_NAME -h WRITE_ENDPOINT
  

Esegui le seguenti sostituzioni:

• DATABASE_NAME: il nome del database. Ad esempio, postgres.
• WRITE_ENDPOINT: il nome DNS o l'endpoint di scrittura. Questo valore alfanumerico termina sempre con il .global.sql-psa.goog. suffisso. Ad esempio, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..

Connetti i client di database alle istanze di database utilizzando l'endpoint di scrittura tramite una connessione SSL/TLS

psql

Per connettere i client di database alle istanze utilizzando un endpoint di scrittura tramite un connessione SSL/TLS, esegui il seguente comando:

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

Esegui le seguenti sostituzioni:

• SSL_MODE: la modalità SSL utilizzata. Ad esempio, verify-full.
• SSL_ROOT_SERVER: il nome del server root SSL. Ad esempio, server-ca.pem.
• SSL_CERT: il nome del certificato SSL utilizzato dal client. Ad esempio, client-cert.pem.
• SSL_KEY: il nome della chiave SSL utilizzata dal client. Ad esempio, client-key.pem.
• WRITE_ENDPOINT: il nome DNS o l'endpoint di scrittura. Questo valore alfanumerico termina sempre con il .global.sql-psa.goog. suffisso. Ad esempio, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
• PORT: il numero di porta utilizzato. Ad esempio, 5432.
• USERNAME: il nome utente. Ad esempio, postgres.
• DATABASE_NAME: il nome del database. Ad esempio, postgres.

Connetti i client di database alle istanze utilizzando il proxy di autenticazione Cloud SQL o i connettori dei linguaggi di Cloud SQL

Quando configuri il proxy di autenticazione Cloud SQL o uno dei connettori dei linguaggi di Cloud SQL utilizzando un nome DNS dell'endpoint di scrittura, il connettore Cloud SQL verifica periodicamente la presenza di un' operazione di switchover o failover. Quando il connettore Cloud SQL rileva che il nome DNS dell'endpoint di scrittura si riferisce a un'istanza diversa, chiude tutte le connessioni aperte alla vecchia istanza. I tentativi di connessione successivi vengono indirizzati alla nuova istanza.

Attenzione: assicurati di avvisare i proprietari delle applicazioni prima di avviare un'operazione di switchover o failover. Durante lo switchover e il failover, il connettore o il proxy di autenticazione terminano forzatamente tutte le connessioni di database aperte.

Supponiamo, ad esempio, che un'applicazione sia configurata per connettersi utilizzando il nome DNS dell'endpoint di scrittura 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog. Inizialmente, la zona DNS è configurata con un record che punta all'istanza principale, my-project:region:instance-a. L'applicazione stabilisce connessioni all'istanza Cloud SQL my-project:region:instance-a.

Quando si verifica il failover o lo switchover, Cloud SQL aggiorna il record DNS da my-project:region:instance-a all'istanza replica di ripristino di emergenza designata: my-project:other-region:instance-b.

Il connettore Cloud SQL utilizzato dall'applicazione rileva la modifica di questo record DNS. Quando l'applicazione si connette al database utilizzando il nome DNS dell'endpoint di scrittura 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog, si connette all'istanza Cloud SQL my-project:other-region:instance-b.

Il connettore o il proxy di autenticazione chiude automaticamente tutte le connessioni esistenti a my-project:region:instance-a. In questo modo, tutti i pool di connessioni utilizzati dall'applicazione devono stabilire nuove connessioni. Può anche causare l'esito negativo delle query di database in corso.

Il proxy di autenticazione Cloud SQL esegue il polling per verificare le modifiche al nome DNS ogni 30 secondi.

Aggiorna la configurazione di rete dell'istanza

Se l'istanza è stata creata prima dell'8 agosto 2025, potresti dover aggiornare la configurazione di rete dell'istanza per consentire ai connettori dei linguaggi di Cloud SQL o al proxy di autenticazione Cloud SQL di utilizzare l'endpoint di scrittura. Devi eseguire questa attività di aggiornamento una sola volta per ogni istanza. Esegui questo comando:

gcloud CLI

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

Esegui le seguenti sostituzioni:

• PRIMARY_NAME: il nome dell'istanza. Ad esempio, my-instance

Connetti i client di database alle istanze utilizzando il proxy di autenticazione Cloud SQL

Per connetterti a un'istanza Cloud SQL tramite il relativo endpoint di scrittura e utilizzando il proxy di autenticazione Cloud SQL, avvia prima il proxy utilizzando l'endpoint di scrittura anziché il nome di connessione dell'istanza.

psql

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT
  

Quindi configura il client di database per connetterti al proxy di autenticazione Cloud SQL:

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

Esegui le seguenti sostituzioni:

• WRITE_ENDPOINT: il nome DNS o l'endpoint di scrittura. Questo valore alfanumerico termina sempre con il .global.sql-psa.goog. suffisso. Ad esempio, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
• PORT: il numero di porta utilizzato. Ad esempio, 5432.
• USERNAME: il nome utente. Ad esempio, postgres.
• DATABASE_NAME: il nome del database. Ad esempio, postgres.

Connettiti utilizzando i connettori dei linguaggi di Cloud SQL

Per connetterti utilizzando uno dei connettori dei linguaggi di Cloud SQL, configura l'applicazione seguendo le istruzioni riportate nella documentazione Connessione tramite i connettori dei linguaggi di Cloud SQL. Modifica quindi la connessione al database in modo che utilizzi l'endpoint di scrittura anziché il nome DNS dell'istanza.

Java

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

Esegui le seguenti sostituzioni:

• WRITE_ENDPOINT: il nome DNS o l'endpoint di scrittura. Questo valore alfanumerico termina sempre con il .global.sql-psa.goog. suffisso.
• DATABASE_NAME: il nome del database. Ad esempio, my-database.
• USERNAME: il nome utente. Ad esempio, postgres.
• PASSWORD: la password del database.

Per saperne di più, consulta la documentazione del connettore Java su GitHub.

Vai

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

Esegui le seguenti sostituzioni:

• WRITE_ENDPOINT: il nome DNS o l'endpoint di scrittura. Questo valore alfanumerico termina sempre con il .global.sql-psa.goog. suffisso.
• DATABASE_NAME: il nome del database. Ad esempio, my-database.
• USERNAME: il nome utente. Ad esempio, postgres.
• PASSWORD: la password del database.

Per saperne di più, consulta la documentazione del connettore Go su GitHub.

Python

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

Esegui le seguenti sostituzioni:

• WRITE_ENDPOINT: il nome DNS o l'endpoint di scrittura. Questo valore alfanumerico termina sempre con il .global.sql-psa.goog. suffisso.
• DATABASE_NAME: il nome del database. Ad esempio, my-database.
• USERNAME: il nome utente. Ad esempio, postgres.
• PASSWORD: la password del database.

Per saperne di più, consulta la documentazione del connettore Python su GitHub.

Node.js

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

Esegui le seguenti sostituzioni:

• WRITE_ENDPOINT: il nome DNS o l'endpoint di scrittura. Questo valore alfanumerico termina sempre con il .global.sql-psa.goog. suffisso.
• DATABASE_NAME: il nome del database. Ad esempio, my-database.
• USERNAME: il nome utente. Ad esempio, postgres.
• PASSWORD: la password del database.

Per saperne di più, consulta la documentazione del connettore Node.js su GitHub.

Limitazioni

• Gli endpoint di scrittura non sono disponibili per le creazioni di istanze Cloud SQL Enterprise.
• Gli endpoint di scrittura non sono disponibili per le istanze con solo IP pubblico o solo Private Service Connect.

Risoluzione dei problemi

Le sezioni seguenti descrivono l'architettura degli endpoint di scrittura e trattano i problemi comuni di risoluzione dei problemi.

Architettura di un endpoint di scrittura

Quando crei un'istanza idonea, viene generato un endpoint di scrittura per impostazione predefinita.

Per creare un endpoint di scrittura, Cloud SQL esegue la seguente configurazione:

• Crea una zona DNS privata nella rete VPC del producer di servizi Cloud SQL
• Crea una zona DNS di peering nella rete VPC del cliente
• Crea un record DNS nella zona DNS privata nella rete del producer di servizi

Il seguente diagramma illustra il funzionamento di questo processo:

Figura 1. Diagramma che mostra come il peering VPC supporta il peering della zona DNS tra una rete del producer di servizi e una rete del cliente.

Problemi di risoluzione DNS

Se la risoluzione DNS non funziona, controlla ciascuno dei seguenti elementi:

1. Assicurati che tutti i prerequisiti siano soddisfatti.
2. Assicurati che i client in cui è prevista la risoluzione si trovino in nella stessa rete a cui è collegata l'istanza Cloud SQL. Per verificarlo, utilizza il gcloud compute instances list comando:

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

   Sostituisci PROJECT_NAME con il nome del progetto in cui si trova la rete consumer DNS risiede.

3. Verifica che la zona di peering esista. Per farlo, utilizza il gcloud dns managed-zones list comando:

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

   Sostituisci PROJECT_NAME con il nome del progetto in cui si trova la rete consumer DNS.

4. Se la zona di peering non esiste, puoi risolvere il problema utilizzando il gcloud sql instances patch comando:

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

   Sostituisci INSTANCE_NAME con il nome dell'istanza Cloud SQL.

La nuova istanza non ha un endpoint di scrittura

Se un'istanza appena creata non contiene un endpoint di scrittura, controlla ciascuno dei seguenti elementi:

1. Assicurati che tutti i prerequisiti siano soddisfatti.
2. Assicurati che non esista una zona DNS di peering residua con il nome DNS sql-psa.goog..

   Una zona DNS di peering è una zona DNS residua se la rete associata a la zona DNS non ha un peering VPC con l'ID progetto peer della zona DNS di peering.

   Se esiste una zona DNS di peering residua con il sql-psa.goog. suffisso, eliminala.

   Attenzione: presta la massima attenzione quando elimini la zona DNS di peering. Se elimini la zona DNS errata, puoi causare la perdita di connettività per tutte le istanze collegate alla rete.

   Per verificare la presenza di zone DNS di peering residue, utilizza il gcloud dns managed-zones list comando:

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

   Sostituisci PROJECT_NAME con il nome del progetto in cui si trova la rete consumer DNS.

   Se esiste una zona DNS con il suffisso sql-psa.goog., eliminala dopo aver verificato che la zona DNS di peering sia una zona DNS residua.

   Per eliminare una zona DNS, utilizza il comando gcloud dns managed-zones delete:

   gcloud dns managed-zones delete ZONE_NAME

   Sostituisci ZONE_NAME con il nome della zona DNS associata agli endpoint di scrittura. I valori sono alfanumerici e utilizzano il seguente formato: cloud-sql-psa-dns-1234567890.

3. Puoi correggere un endpoint di scrittura mancante per un'istanza idonea utilizzando il comando gcloud beta sql instances patch:

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

   Sostituisci INSTANCE_NAME con il nome dell'istanza Cloud SQL.

Passaggi successivi

• Scopri di più sulla risoluzione dei problemi di Cloud SQL.