Verbindung zu einer Instanz über einen Schreibendpunkt herstellen

MySQL   |  PostgreSQL   |  SQL Server

Übersicht

Auf dieser Seite wird beschrieben, wie Sie einen Schreibendpunkt verwenden, um von Clients in Ihrem Virtual Private Cloud-Netzwerk (VPC) über den Zugriff auf private Dienste (Private Services Access, PSA) eine Verbindung zu einer Cloud SQL-Instanz herzustellen.

Ein Schreibendpunkt ist ein globaler DNS-Name (Domain Name Service), der automatisch in die IP-Adresse der aktuellen primären Instanz aufgelöst wird. Bei einem Replikat- Failover oder Switchover -Vorgang leitet dieser Schreibendpunkt eingehende Verbindungen automatisch zur neuen primären -Instanz um. Sie können den Schreibendpunkt in einer SQL-Verbindungsstring zur Cloud SQL-Instanz verwenden, anstatt eine IP-Adresse zu verwenden. Wenn Sie einen Schreibendpunkt verwenden, müssen Sie keine Änderungen an der Anwendungsverbindung vornehmen, wenn Sie ein Failover oder Switchover des Replikats zur Wiederherstellung nach einem regionalen Ausfall oder für eine Notfallwiederherstellungsübung durchführen.

Jede infrage kommende Cloud SQL-Instanz hat einen einzelnen integrierten Schreibendpunkt, dessen Name, Erstellung und Aktualisierung von Cloud SQL verwaltet werden. Das folgende Beispiel veranschaulicht das Format:

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

Der Schreibendpunkt endet immer mit dem Suffix .global.sql-psa.goog.. Sie können den Namen oder das Format dieses von Cloud SQL verwalteten Schreibendpunkts nicht ändern.

Sie können den Schreibendpunkt für alle Schreibvorgänge in der primären Instanz verwenden, einschließlich Einfügungen, Aktualisierungen, Löschungen und DDL-Änderungen. Sie können den Schreibendpunkt auch für Lesevorgänge wie Abfragen verwenden. Die private IP-Adresse, auf die der Schreibendpunkt verweist, wird von Cloud SQL automatisch geändert, wenn Sie ein Failover oder Switchover des Replikats durchführen, um eine Replikatinstanz zur neuen primären Instanz hochzustufen.

Schreibendpunkt generieren

Wenn Sie eine neue Cloud SQL-Instanz erstellen, erstellt Cloud SQL den Schreibendpunkt automatisch, wenn die folgenden Voraussetzungen erfüllt sind:

• Die folgenden APIs müssen in dem Google Cloud Projekt aktiviert sein, in dem sich Ihre Cloud SQL-Instanz befindet:
  • Compute Engine API
  • Cloud DNS API

  Wenn Sie die Cloud DNS API im Projekt nicht aktivieren, kann die Peering-DNS-Zone nicht erstellt werden, wodurch die DNS-Namen unbrauchbar werden.

  Sobald die Peering-DNS-Zone erstellt wurde, darf sie nicht mehr geändert werden. Alle Änderungen, einschließlich des Löschens, machen das DNS für die Datenbankverbindung unbrauchbar.

• Die Cloud SQL-Instanz muss die Cloud SQL Enterprise Plus-Version sein.
• Die Cloud SQL-Instanz muss für die Verwendung einer privaten IP-Adresse konfiguriert sein, wobei der Zugriff auf private Dienste (Private Services Access, PSA) aktiviert sein muss.
• Für die Funktion sind Instanzen in der neuen Netzwerkarchitektur erforderlich. In den meisten Fällen werden neue Instanzen mit der neuen Architektur erstellt. Prüfen Sie dazu, die Netzwerkarchitektur Ihrer Instanz.

Wenn Sie eine vorhandene Cloud SQL Enterprise-Instanz auf eine Cloud SQL Enterprise Plus-Instanz aktualisieren, generiert Cloud SQL den Schreibendpunkt automatisch, wenn die oben aufgeführten Voraussetzungen erfüllt sind. Wenn sich Ihre vorhandene Instanz in der alten Netzwerk architektur befindet, müssen Sie die Instanz zuerst auf die neue Netzwerkarchitektur aktualisieren, um den Schreibendpunkt zu erhalten.

Wenn Sie bereits eine Cloud SQL Enterprise Plus-Instanz ohne Schreibendpunkt haben und möchten, dass Cloud SQL automatisch einen Schreibendpunkt generiert, erstellen Sie ein Replikat, das für die erweiterte Notfallwiederherstellung aktiviert ist.

Schreibendpunkt ansehen

gcloud

Verwenden Sie den folgenden gcloud CLI-Befehl, um den Schreibendpunkt zu finden:

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

Ersetzen Sie die folgenden Werte:

INSTANCE_NAME: Der Name der Cloud SQL-Instanz.

Schreibendpunkte enden immer mit dem Suffix .global.sql-psa.goog., ähnlich dem folgenden Beispiel:

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

Wenn der Schreibendpunkt für eine infrage kommende Instanz nicht angezeigt wird, lesen Sie den Abschnitt zur Fehlerbehebung.

Verbindung zu einer Cloud SQL-Instanz über einen Schreibendpunkt herstellen

psql

Führen Sie den folgenden Befehl aus, um einen psql Client über den Schreibendpunkt mit einer Cloud SQL-Instanz zu verbinden:

    psql -U DATABASE_NAME -h WRITE_ENDPOINT
  

Ersetzen Sie die folgenden Werte:

• DATABASE_NAME: Der Name der Datenbank. Beispiel: postgres.
• WRITE_ENDPOINT: Der DNS-Name oder Schreibendpunkt. Dieser alphanumerische Wert endet immer mit dem .global.sql-psa.goog. Suffix. Beispiel: 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..

Datenbankclients über eine SSL/TLS-Verbindung mit Datenbankinstanzen verbinden

psql

Führen Sie den folgenden Befehl aus, um Datenbankclients über eine SSL/TLS-Verbindung mit Instanzen zu verbinden:

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

Ersetzen Sie die folgenden Werte:

• SSL_MODE: Der verwendete SSL-Modus. Beispiel: verify-full.
• SSL_ROOT_SERVER: Der Name des SSL-Stammservers. Beispiel: server-ca.pem.
• SSL_CERT: Der Name des SSL-Zertifikats, das vom Client verwendet wird. Beispiel: client-cert.pem.
• SSL_KEY: Der Name des SSL-Schlüssels, der vom Client verwendet wird. Beispiel: client-key.pem.
• WRITE_ENDPOINT: Der DNS-Name oder Schreibendpunkt. Dieser alphanumerische Wert endet immer mit dem .global.sql-psa.goog. Suffix. Beispiel: 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
• PORT: Die verwendete Portnummer. Beispiel: 5432.
• USERNAME: Der Nutzername. Beispiel: postgres.
• DATABASE_NAME: Der Name der Datenbank. Beispiel: postgres.

Datenbankclients über den Cloud SQL Auth-Proxy oder Cloud SQL Language Connectors mit Instanzen verbinden

Wenn Sie den Cloud SQL Auth-Proxy oder einen der Cloud SQL Language Connectors mit einem DNS-Namen für den Schreibendpunkt konfigurieren, prüft der Cloud SQL-Connector regelmäßig auf einen Switchover oder Failover-Vorgang. Wenn der Cloud SQL-Connector feststellt, dass der DNS-Name des Schreibendpunkts auf eine andere Instanz verweist, schließt er alle offenen Verbindungen zur alten Instanz. Nachfolgende Verbindungsversuche werden an die neue Instanz weitergeleitet.

Achtung: Benachrichtigen Sie die Anwendungsbesitzer, bevor Sie einen Switchover- oder Failover-Vorgang starten. Während des Switchovers und Failovers beendet der Connector oder Auth-Proxy alle offenen Datenbankverbindungen.

Angenommen, eine Anwendung ist so konfiguriert, dass sie eine Verbindung über den Schreib endpunkt-DNS-Namen 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog herstellt. Anfangs ist die DNS-Zone mit einem Eintrag konfiguriert, der auf die primäre Instanz my-project:region:instance-a verweist. Die Anwendung stellt Verbindungen zur Cloud SQL-Instanz my-project:region:instance-a her.

Wenn das Failover oder Switchover erfolgt, aktualisiert Cloud SQL den DNS-Eintrag von my-project:region:instance-a auf die angegebene DR-Replikat Instanz: my-project:other-region:instance-b.

Der von der Anwendung verwendete Cloud SQL-Connector erkennt die Änderung an diesem DNS-Eintrag. Wenn die Anwendung über den DNS-Namen des Schreib endpunkts 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog, eine Verbindung zu ihrer Datenbank herstellt, stellt sie eine Verbindung zur my-project:other-region:instance-b Cloud SQL-Instanz her.

Der Connector oder Auth-Proxy schließt automatisch alle vorhandenen Verbindungen zu my-project:region:instance-a. Dadurch werden alle von der Anwendung verwendeten Verbindungspools gezwungen, neue Verbindungen herzustellen. Außerdem können dadurch laufende Datenbankabfragen fehlschlagen.

Der Cloud SQL Auth-Proxy fragt alle 30 Sekunden nach Änderungen am DNS-Namen.

Netzwerkkonfiguration der Instanz aktualisieren

Wenn Ihre Instanz vor dem 8. August 2025 erstellt wurde, müssen Sie möglicherweise die Netzwerkkonfiguration der Instanz aktualisieren, damit Cloud SQL Language Connectors oder der Cloud SQL Auth-Proxy den Schreibendpunkt verwenden können. Sie müssen diese Aktualisierungsaufgabe nur einmal für jede Instanz ausführen. Führen Sie dazu diesen Befehl aus:

gcloud-CLI

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

Ersetzen Sie die folgenden Werte:

• PRIMARY_NAME: Der Name der Instanz. Beispiel: my-instance

Datenbankclients über den Cloud SQL Auth-Proxy mit Instanzen verbinden

Wenn Sie über den Schreibendpunkt und den Cloud SQL Auth-Proxy eine Verbindung zu einer Cloud SQL-Instanz herstellen möchten, starten Sie zuerst den Proxy mit dem Schreibendpunkt anstelle des Instanzverbindungsnamens.

psql

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT
  

Konfigurieren Sie dann den Datenbankclient so, dass er eine Verbindung zum Cloud SQL Auth-Proxy herstellt:

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

Ersetzen Sie die folgenden Werte:

• WRITE_ENDPOINT: Der DNS-Name oder Schreibendpunkt. Dieser alphanumerische Wert endet immer mit dem .global.sql-psa.goog. Suffix. Beispiel: 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
• PORT: Die verwendete Portnummer. Beispiel: 5432.
• USERNAME: Der Nutzername. Beispiel: postgres.
• DATABASE_NAME: Der Name der Datenbank. Beispiel: postgres.

Verbindung über Cloud SQL Language Connectors herstellen

Wenn Sie eine Verbindung über einen der Cloud SQL Language Connectors herstellen möchten, konfigurieren Sie Ihre Anwendung gemäß der Anleitung unter Verbindung über Cloud SQL Language Connectors herstellen. Ändern Sie dann Ihre Datenbankverbindung so, dass der Schreibendpunkt anstelle des DNS-Namens der Instanz verwendet wird.

Java

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

Ersetzen Sie die folgenden Werte:

• WRITE_ENDPOINT: Der DNS-Name oder Schreibendpunkt. Dieser alphanumerische Wert endet immer mit dem .global.sql-psa.goog. Suffix.
• DATABASE_NAME: Der Name der Datenbank. Beispiel: my-database.
• USERNAME: Der Nutzername. Beispiel: postgres.
• PASSWORD: Das Datenbankpasswort.

Weitere Informationen finden Sie in der Java-Connector-Dokumentation auf GitHub.

Go

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

Ersetzen Sie die folgenden Werte:

• WRITE_ENDPOINT: Der DNS-Name oder Schreibendpunkt. Dieser alphanumerische Wert endet immer mit dem .global.sql-psa.goog. Suffix.
• DATABASE_NAME: Der Name der Datenbank. Beispiel: my-database.
• USERNAME: Der Nutzername. Beispiel: postgres.
• PASSWORD: Das Datenbankpasswort.

Weitere Informationen finden Sie in der Go-Connector-Dokumentation auf 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"
      ),
  )
  

Ersetzen Sie die folgenden Werte:

• WRITE_ENDPOINT: Der DNS-Name oder Schreibendpunkt. Dieser alphanumerische Wert endet immer mit dem .global.sql-psa.goog. Suffix.
• DATABASE_NAME: Der Name der Datenbank. Beispiel: my-database.
• USERNAME: Der Nutzername. Beispiel: postgres.
• PASSWORD: Das Datenbankpasswort.

Weitere Informationen finden Sie in der Python-Connector-Dokumentation auf 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,
  });
  

Ersetzen Sie die folgenden Werte:

• WRITE_ENDPOINT: Der DNS-Name oder Schreibendpunkt. Dieser alphanumerische Wert endet immer mit dem .global.sql-psa.goog. Suffix.
• DATABASE_NAME: Der Name der Datenbank. Beispiel: my-database.
• USERNAME: Der Nutzername. Beispiel: postgres.
• PASSWORD: Das Datenbankpasswort.

Weitere Informationen finden Sie in der Node.js-Connector-Dokumentation auf GitHub.

Beschränkungen

• Schreibendpunkte sind für die Erstellung von Cloud SQL Enterprise-Instanzen nicht verfügbar.
• Schreibendpunkte sind nicht für Instanzen mit nur öffentlicher IP-Adresse oder nur Private Service Connect-Instanzen verfügbar.

Fehlerbehebung

In den folgenden Abschnitten wird die Architektur von Schreibendpunkten beschrieben und auf häufige Probleme bei der Fehlerbehebung eingegangen.

Architektur eines Schreibendpunkts

Wenn Sie eine infrage kommende Instanz erstellen, wird standardmäßig ein Schreibendpunkt generiert.

Um einen Schreibendpunkt zu erstellen, führt Cloud SQL die folgende Einrichtung durch:

• Erstellt eine private DNS-Zone im VPC-Netzwerk des Cloud SQL-Diensterstellers
• Erstellt eine Peering-DNS-Zone im VPC-Netzwerk des Kunden
• Erstellt einen DNS-Eintrag in der privaten DNS-Zone im Netzwerk des Diensterstellers

Das folgende Diagramm veranschaulicht diesen Prozess:

Abbildung 1. Diagramm, das zeigt, wie VPC-Peering das DNS-Zonen Peering zwischen einem Dienstersteller- und einem Kundennetzwerk unterstützt.

Probleme mit der DNS-Auflösung

Wenn die DNS-Auflösung nicht funktioniert, prüfen Sie die folgenden Punkte:

1. Achten Sie darauf, dass alle Voraussetzungen erfüllt sind.
2. Achten Sie darauf, dass sich die Clients, auf denen die Auflösung erwartet wird, in demselben Netzwerk befinden, mit dem die Cloud SQL-Instanz verbunden ist. Verwenden Sie dazu den gcloud compute instances list Befehl:

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

   Ersetzen Sie PROJECT_NAME durch den Namen des Projekts, in dem sich das DNS-Nutzerprojekt befindet.

3. Prüfen Sie, ob die Peering-Zone vorhanden ist. Verwenden Sie dazu den gcloud dns managed-zones list Befehl:

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

   Ersetzen Sie PROJECT_NAME durch den Namen des Projekts, in dem sich das DNS-Nutzerprojekt befindet.

4. Wenn die Peering-Zone nicht vorhanden ist, können Sie das Problem mit dem gcloud sql instances patch Befehl beheben:

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

   Ersetzen Sie INSTANCE_NAME durch den Namen Ihrer Cloud SQL-Instanz.

Neue Instanz hat keinen Schreibendpunkt

Wenn eine neu erstellte Instanz keinen Schreibendpunkt enthält, prüfen Sie die folgenden Punkte:

1. Achten Sie darauf, dass alle Voraussetzungen erfüllt sind.
2. Achten Sie darauf, dass keine übrig gebliebene Peering-DNS-Zone mit dem DNS-Namen sql-psa.goog. vorhanden ist.

   Eine Peering-DNS-Zone ist eine übrig gebliebene DNS-Zone, wenn das mit der DNS-Zone verknüpfte Netzwerk kein VPC-Peering mit der Peer-Projekt-ID der Peering-DNS-Zone hat.

   Wenn eine übrig gebliebene Peering-DNS-Zone mit dem sql-psa.goog. Suffix vorhanden ist, löschen Sie sie.

   Achtung: Seien Sie beim Löschen der Peering-DNS-Zone äußerst vorsichtig. Wenn Sie die falsche DNS-Zone löschen, kann dies zu einem Verbindungsverlust für alle Instanzen führen, die mit dem Netzwerk verbunden sind.

   Verwenden Sie den gcloud dns managed-zones list Befehl, um nach übrig gebliebenen Peering-DNS-Zonen zu suchen:

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

   Ersetzen Sie PROJECT_NAME durch den Namen des Projekts, in dem sich das DNS-Nutzerprojekt befindet.

   Wenn eine DNS-Zone mit dem Suffix sql-psa.goog. vorhanden ist, löschen Sie die DNS-Zone, nachdem Sie noch einmal geprüft haben, ob die Peering-DNS-Zone eine übrig gebliebene DNS-Zone ist.

   Verwenden Sie den Befehl gcloud dns managed-zones delete, um eine DNS-Zone zu löschen:

   gcloud dns managed-zones delete ZONE_NAME

   Ersetzen Sie ZONE_NAME durch den DNS-Zonennamen, der mit den Schreibendpunkten verknüpft ist. Die Werte sind alphanumerisch und haben das folgende Format: cloud-sql-psa-dns-1234567890.

3. Sie können einen fehlenden Schreibendpunkt für eine infrage kommende Instanz mit dem Befehl gcloud beta sql instances patch beheben:

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

   Ersetzen Sie INSTANCE_NAME durch den Namen Ihrer Cloud SQL-Instanz.

Nächste Schritte

• Weitere Informationen zur Fehlerbehebung in Cloud SQL