Direkte Datenbankaktualisierung durchführen

Auf dieser Seite wird beschrieben, wie Sie die Hauptversion der Datenbank aktualisieren, indem Sie Ihre Cloud SQL-Instanz direkt aktualisieren, anstatt Daten zu migrieren.

Einführung

Anbieter von Datenbanksoftware veröffentlichen regelmäßig neue Hauptversionen, die neue Features, Leistungsverbesserungen und Sicherheitsverbesserungen enthalten. Cloud SQL übernimmt neue Versionen nach der Veröffentlichung. Sobald Cloud SQL Unterstützung für eine neue Hauptversion bietet, können Sie ein Upgrade Ihrer Instanzen durchführen, um die Datenbank auf dem neuesten Stand zu halten.

Sie können die Datenbankversion einer Instanz direkt aktualisieren oder Daten migrieren. Direkte Upgrades sind eine einfache Möglichkeit, ein Upgrade der Hauptversion einer Instanz durchzuführen. Sie müssen keine Daten migrieren oder Anwendungsverbindungsstrings ändern. Bei direkten Upgrades können Sie den Namen, die IP-Adresse und andere Einstellungen Ihrer aktuellen Instanz nach dem Upgrade beibehalten. Für direkte Upgrades ist es nicht erforderlich, Datendateien zu verschieben, und sie können schneller ausgeführt werden. In einigen Fällen ist die Ausfallzeit kürzer als bei der Migration Ihrer Daten.

Upgrade einer Hauptversion planen

1. Wählen Sie eine Ziel-Hauptversion aus.

   gcloud

   Informationen zur Installation und zu den ersten Schritten mit der gcloud CLI finden Sie unter gcloud CLI installieren. Informationen zum Starten von Cloud Shell finden Sie unter Cloud Shell verwenden.

   So prüfen Sie, auf welche Datenbankversionen Sie ein In-Place-Upgrade auf Ihrer Instanz ausführen können:

   1. Führen Sie den folgenden Befehl aus:

   gcloud sql instances describe INSTANCE_NAME
      

   Ersetzen Sie INSTANCE_NAME durch den Namen der Instanz.

   2. Suchen Sie in der Ausgabe des Befehls nach dem Abschnitt mit der Bezeichnung upgradableDatabaseVersions.
   3. Jeder Abschnitt gibt eine Datenbankversion zurück, die für ein Upgrade verfügbar ist. Prüfen Sie in jedem Unterabschnitt die folgenden Felder.
   • majorVersion: die Hauptversion, auf die das In-Place-Upgrade ausgerichtet werden kann.
   • name: den String der Datenbankversion, der die Hauptversion enthält.
   • displayName: den Anzeigenamen der Datenbankversion.

   REST Version 1

   Mit der Methode instances.get der Cloud SQL Admin API können Sie prüfen, welche Zieldatenbankversionen für ein direktes Upgrade auf eine neue Hauptversion verfügbar sind.

   Ersetzen Sie diese Werte in den folgenden Anfragedaten:

   • INSTANCE_NAME: ist der Name der Instanz.

   HTTP-Methode und URL:

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

   Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

   curl (Linux, macOS oder Cloud Shell)

   Führen Sie folgenden Befehl aus:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell (Windows)

   Führen Sie folgenden Befehl aus:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   Sie sollten in etwa folgende JSON-Antwort erhalten:

   
   upgradableDatabaseVersions:
   
   {
     major_version: "POSTGRES_15_0"
     name: "POSTGRES_15_0"
     display_name: "PostgreSQL 15.0"
   }
   
   

   REST v1beta4

   Mit der Methode instances.get der Cloud SQL Admin API können Sie prüfen, welche Zieldatenbankversionen für ein direktes Upgrade einer Instanz auf eine Hauptversion verfügbar sind.

   Ersetzen Sie diese Werte in den folgenden Anfragedaten:

   • INSTANCE_NAME: ist der Name der Instanz.

   HTTP-Methode und URL:

   GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

   Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

   curl (Linux, macOS oder Cloud Shell)

   Führen Sie folgenden Befehl aus:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell (Windows)

   Führen Sie folgenden Befehl aus:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   Sie sollten in etwa folgende JSON-Antwort erhalten:

   
   upgradableDatabaseVersions:
   
   {
     major_version: "POSTGRES_15_0"
     name: "POSTGRES_15_0"
     display_name: "PostgreSQL 15.0"
   }
   
   

   Eine vollständige Liste der von Cloud SQL unterstützten Datenbankversionen finden Sie unter Datenbankversionen und Versionsrichtlinien.

2. Berücksichtigen Sie die in den einzelnen Datenbankversionen verfügbaren Versions- und Adressinkompatibilitäten.

   • PostgreSQL 17
   • PostgreSQL 16
   • PostgreSQL 15
   • PostgreSQL 14
   • PostgreSQL 13
   • PostgreSQL 12
   • PostgreSQL 11
   • PostgreSQL 10

   Neue Hauptversionen führen inkompatible Änderungen ein, sodass Sie möglicherweise den Anwendungscode, das Schema oder die Datenbankeinstellungen ändern müssen. Bevor Sie ein Upgrade für Ihre Datenbankinstanz durchführen können, lesen Sie die Versionshinweise Ihrer Zielhauptversion, um zu ermitteln, welche Inkompatibilitäten berücksichtigt werden müssen.

3. Testen Sie das Upgrade im Probelauf.

   Führen Sie einen Probelauf des End-to-End-Upgradeprozesses in einer Testumgebung durch, bevor Sie die Produktionsdatenbank aktualisieren. Sie können Ihre Instanz klonen, um eine identische Kopie der Daten zu erstellen, bei denen Sie den Upgradeprozess testen können.

   Überprüfen Sie nicht nur, ob das Upgrade erfolgreich abgeschlossen wurde, sondern führen Sie auch Tests durch, um sicherzustellen, dass sich die Anwendung auf der aktualisierten Datenbank wie erwartet verhält.

4. Legen Sie einen Zeitpunkt für das Upgrade fest.

   Für ein Upgrade darf die Instanz für einen bestimmten Zeitraum nicht verfügbar sein. Planen Sie das Upgrade in einem Zeitraum niedriger Datenbankaktivität.

Upgrade auf eine Hauptversion vorbereiten

Führen Sie vor dem Upgrade die folgenden Schritte au:

1. Prüfen Sie den Wert LC_COLLATE für die Datenbanken template und postgres. Der Zeichensatz für jede Datenbank muss en_US.UTF8 sein.

   Wenn der Wert LC_COLLATE für die Datenbanken template und postgres nicht en_US.UTF8 ist, schlägt das Hauptversion-Upgrade fehl. Um dieses Problem zu beheben, ändern Sie den Wert LC_COLLATE vor dem Upgrade in en_US.UTF8, wenn eine der Datenbanken einen anderen Zeichensatz als en_US.UTF8 hat.

   So ändern Sie die Codierung einer Datenbank:

   1. Erstellen Sie einen Dump Ihrer Datenbank.
   2. Löschen Sie Ihre Datenbank.
   3. Erstellen Sie eine neue Datenbank mit einer anderen Codierung (in diesem Beispiel en_US.UTF8).
   4. Laden Sie die Daten neu.

   Sie können die Datenbank auch umbenennen:

   1. Schließen Sie alle Verbindungen zur Datenbank.
   2. Benennen Sie die Datenbank um.
   3. Aktualisieren Sie Ihre Anwendungskonfigurationen, damit der neue Datenbankname verwendet wird.
   4. Erstellen Sie eine neue, leere Datenbank mit der Standardcodierung.

   Wir empfehlen, diese Schritte auf einer geklonten Instanz auszuführen, bevor Sie sie auf eine Produktionsinstanz anwenden.

2. Verwalten Sie Ihre Lesereplikate.

   Cloud SQL for PostgreSQL unterstützt keine versionsübergreifende Replikation. Das bedeutet, dass Sie die primäre Instanz nicht aktualisieren können, während die Instanz auf die Lesereplikate repliziert. Deaktivieren Sie vor dem Upgrade entweder die Replikation für jedes Lesereplikat oder löschen Sie die Lesereplikate.

3. Wenn Cloud SQL die logische Replikationsquelle ist, deaktivieren Sie die Replikation der Erweiterung pglogical so: Sie können sie nach dem Upgrade wieder aktivieren. Wenn Cloud SQL das logische Replikationsziel ist, sind diese Schritte nicht erforderlich.
   1. Deaktivieren Sie das Abo und trennen Sie das Replikat vom Anbieter. Führen Sie dazu den folgenden Befehl aus:

      SELECT * FROM pglogical.alter_subscription_disable(subscription_name name, immediate bool);

      Ersetzen Sie name durch den Namen des vorhandenen Abos.

      Setzen Sie den Wert des Parameters immediate auf true, wenn das Abo sofort deaktiviert werden muss. Standardmäßig ist der Wert false und das Abo wird erst deaktiviert, wenn die aktuelle Transaktion endet.

      Beispiel:

      postgres=> SELECT * FROM pglogical.alter_subscription_disable('test_sub', true);
       alter_subscription_disable
      ----------------------------
       t
      (1 row)

   2. Löschen Sie den Replikations-Slot. Stellen Sie dazu eine Verbindung zum Publisher oder zur primären Cloud SQL-Instanz her und führen Sie dann den folgenden Befehl aus:

      SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
        WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);

      Beispiel:

      postgres=> SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
      postgres->    WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);
      -[ RECORD 1 ]------------+-
      pg_drop_replication_slot |
      
      postgres=>

4. Verwalten Sie Ihre verbleibenden PostgreSQL-Erweiterungen.

   Die meisten Erweiterungen funktionieren mit der aktualisierten Hauptversion der Datenbank. Löschen Sie alle Erweiterungen, die in Ihrer Zielversion nicht mehr unterstützt werden. Löschen Sie beispielsweise die Erweiterung chkpass, wenn Sie ein Upgrade auf PostgreSQL 11 oder höher ausführen.

   Sie können PostGIS und die zugehörigen Erweiterungen manuell auf die neuesten unterstützten Versionen aktualisieren.

   Gelegentlich kann ein Upgrade von PostGIS Versionen 2.x dazu führen, dass Datenbankobjekte Datenbankobjekte übrig bleiben, die nicht mit der PostGIS-Erweiterung verknüpft sind. Dies kann den Upgradevorgang blockieren. Informationen zum Beheben dieses Problems finden Sie unter Beheben einer fehlerhaften PostGIS-Rasterinstallation.

   Manchmal kann das Upgrade auf PostGIS 3.1.7 oder höher nicht abgeschlossen werden, weil Objekte verworfene Funktionen verwenden. Dies kann den Upgradevorgang blockieren. Führen Sie SELECT PostGIS_full_version(); aus, um den Upgrade-Status zu prüfen. Wenn Warnungen vorhanden sind, löschen Sie alle Objekte, die die eingestellten Funktionen verwenden, und aktualisieren Sie die PostGIS-Erweiterung auf eine Zwischenversion oder eine höhere Version. Führen Sie den Befehl SELECT PostGIS_full_version(); dann noch einmal aus. Prüfen Sie, ob keine Warnungen angezeigt werden. Fahren Sie dann mit dem Upgrade fort.

   Weitere Informationen zum Upgraden Ihrer PostGIS-Erweiterungen finden Sie unter PostGIS upgraden. Probleme im Zusammenhang mit dem Upgrade von PostGIS finden Sie unter Version Ihrer PostgreSQL-Instanz prüfen.
5. Verwalten Sie Ihre benutzerdefinierten Datenbank-Flags. Prüfen Sie die Namen aller benutzerdefinierten Datenbank-Flags, die Sie für Ihre PostgreSQL-Instanz konfiguriert haben. Informationen zu Problemen im Zusammenhang mit diesen Flags finden Sie unter Benutzerdefinierte Flags für Ihre PostgreSQL-Instanz prüfen.
6. Wenn Sie ein Upgrade von einer Hauptversion auf eine andere ausführen, sollten Sie versuchen, eine Verbindung zu jeder Datenbank herzustellen, um festzustellen, ob Kompatibilitätsprobleme auftreten. Sorgen Sie dafür, dass Ihre Datenbanken miteinander verbunden werden können. Prüfen Sie das Feld datallowconn für jede Datenbank, um sicherzustellen, dass eine Verbindung zulässig ist. Der Wert t bedeutet, dass dies zulässig ist. Der Wert f gibt an, dass keine Verbindung hergestellt werden kann.
7. Wenn Sie die Installation von Datadog verwenden, um Ihre Cloud SQL-Instanz auf PostgreSQL 10 oder höher zu aktualisieren, löschen Sie vor dem Upgrade die Funktion pg_stat_activity().

Bekannte Einschränkungen

Die folgenden Einschränkungen wirken sich auf In-Place-Hauptversionsupgrades von Cloud SQL for PostgreSQL aus:

• Ein direktes Upgrade einer Hauptversion ist bei einem externen Replikat nicht möglich.
• Das Upgrade von Instanzen mit mehr als 1.000 Datenbanken von einer Version auf eine andere kann lange dauern.
• Mit der Anweisung select * from pg_largeobject_metadata; können Sie die Anzahl der großen Objekte in jeder PostgreSQL-Datenbank Ihrer Cloud SQL-Instanz abfragen. Wenn das Ergebnis aus allen Ihren Datenbanken mehr als 10 Millionen große Objekte beträgt, schlägt das Upgrade fehl. Cloud SQL führt ein Rollback auf die vorherige Version Ihrer Datenbank durch.
• Bevor Sie ein In-Place-Upgrade auf die Hauptversion PostgreSQL 16 oder höher durchführen, aktualisieren Sie die PostGIS-Erweiterung für alle Ihre Datenbanken auf Version 3.4.0.
• Wenn Sie PostgreSQL-Versionen 9.6, 10, 11 oder 12 verwenden, wird Version 3.4.0 der PostGIS-Erweiterung nicht unterstützt. Wenn Sie also ein In-Place-Upgrade auf die Hauptversion PostgreSQL 16 oder höher ausführen möchten, müssen Sie zuerst ein Upgrade auf eine Zwischenversion von PostgreSQL (Versionen 13, 14 oder 15) durchführen.

• Wenn Sie die Erweiterungen pgRouting und pg_squeeze für Ihre Instanz installieren, können Sie kein Upgrade der Hauptversion durchführen. Deinstallieren Sie diese Erweiterungen und führen Sie dann das Upgrade aus. Weitere Informationen zu den Erweiterungen finden Sie unter PostgreSQL-Erweiterungen konfigurieren.

• Wenn Sie die Flags vacuum_defer_cleanup_age und force_parallel_mode aktivieren, können Sie kein Upgrade der Hauptversion ausführen. Löschen Sie diese Flags und führen Sie dann das Upgrade aus. Weitere Informationen zu den Flags und dazu, wie Sie sie löschen, finden Sie unter Datenbank-Flags konfigurieren.

Direkte Datenbankaktualisierung durchführen

Wenn Sie einen Upgradevorgang starten, prüft Cloud SQL zuerst die Konfiguration Ihrer Instanz dahingehend, ob sie für ein Upgrade kompatibel ist. Nach der Prüfung der Konfiguration deaktiviert Cloud SQL Ihre Instanz, erstellt eine Sicherung vor dem Upgrade, führt das Upgrade durch, aktiviert Ihre Instanz und erstellt eine Sicherung nach dem Upgrade.

resource "google_sql_database_instance" "instance" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

Wenn Sie eine direkte Upgradeanfrage stellen, führt Cloud SQL zuerst eine Prüfung vor dem Upgrade durch. Wenn Cloud SQL feststellt, dass die Instanz nicht für ein Upgrade bereit ist, schlägt die Upgradeanfrage mit einer Meldung dazu fehl, wie Sie das Problem beheben können. Weitere Informationen finden Sie unter Fehlerbehebung bei einem Hauptversionsupgrade.

Automatische Upgradesicherungen

Wenn Sie ein Upgrade der Hauptversion durchführen, erstellt Cloud SQL automatisch zwei On-Demand-Sicherungen, die als Upgradesicherungen bezeichnet werden:

• Die erste Upgradesicherung ist die Sicherung vor dem Upgrade, die unmittelbar vor Beginn des Upgrades durchgeführt wird. Mit dieser Sicherung können Sie Ihre Datenbankinstanz auf den Zustand der vorherigen Version zurücksetzen.
• Die zweite Upgrade-Sicherung ist die Sicherung nach dem Upgrade, die sofort erfolgt, nachdem neue Schreibvorgänge auf die aktualisierte Datenbankinstanz zugelassen wurden.

Wenn Sie die Liste Ihrer Sicherungen aufrufen, werden die Upgradesicherungen vom Typ On-demand aufgelistet. Upgrade-Sicherungen sind mit Labels versehen, damit Sie sie schnell identifizieren können. Wenn Sie beispielsweise ein Upgrade von PostgreSQL 14 auf PostgreSQL 15 ausführen, heißt die Sicherung vor dem Upgrade Pre-upgrade backup, POSTGRES_14 to POSTGRES_15. und Ihre Sicherung nach dem Upgrade Post-upgrade backup, POSTGRES_14 to POSTGRES_15..

Wie bei anderen On-Demand-Sicherungen bleiben Upgradesicherungen erhalten, bis Sie sie löschen oder die Instanz löschen. Wenn Sie PITR aktiviert haben, können Sie Ihre Upgradesicherungen nicht löschen, solange diese sich in Ihrem Zeitfenster für die Aufbewahrung befinden. Wenn Sie Ihre Upgradesicherungen löschen möchten, müssen Sie PITR deaktivieren oder warten, bis sich die Upgradesicherungen nicht mehr im Aufbewahrungsfenster befinden.

Upgrade der Hauptversion abschließen

Führen Sie nach der Aktualisierung der primären Instanz die folgenden Schritte aus, um die Aktualisierung abzuschließen:

1. Aktivieren Sie die Replikation von pglogical, wenn Ihre Instanz sie vor dem Upgrade verwendet hat. Dadurch wird automatisch der erforderliche Replikations-Slot erstellt.
   1. Löschen Sie das Abo pglogical auf dem Zielreplikat mit dem folgenden Befehl:

      select pglogical.drop_subscription(subscription_name name);

      Ersetzen Sie name durch den Namen des vorhandenen Abos.

      Beispiel:

      postgres=> select pglogical.drop_subscription(subscription_name := 'test_sub');
      -[ RECORD 1 ]-----+--
      drop_subscription | 1

   2. Erstellen Sie das pglogical-Abo auf dem Ziel (Replikat) neu, indem Sie der primären Cloud SQL-Instanz die folgenden Verbindungsdetails mitteilen:

      SELECT pglogical.create_subscription(
          subscription_name := 'test_sub',
          provider_dsn := 'host=primary-ip port=5432 dbname=postgres user=replication_user password=replicapassword'
      ); 

      Beispiel:

      postgres=> SELECT pglogical.create_subscription(
      postgres(>     subscription_name := 'test_sub',
      postgres(>     provider_dsn := 'host=10.58.64.90 port=5432 dbname=postgres user=postgres password=postgres'
      postgres(> );
      -[ RECORD 1 ]-------+-----------
      create_subscription | 2769129391

   3. Prüfen Sie den Status des Abos mit folgendem Befehl:

      SELECT * FROM pglogical.show_subscription_status('test_sub');

   4. Testen Sie die Replikation, indem Sie Schreibtransaktionen ausführen und prüfen, ob die Änderungen am Ziel sichtbar sind.

2. Aktualisieren Sie die Lesereplikate.

   Wenn Sie die Replikation zum Lesen von Replikaten beendet haben, aktualisieren Sie sie nacheinander. Sie können jede der Methoden verwenden, die zum Aktualisieren der primären Instanz verwendet werden. Beim Upgrade eines Replikats wird dieses von Cloud SQL unter Beibehaltung der IP-Adressen neu erstellt. Das Replikat wird mit den neuesten Daten der primären Instanz aktualisiert und neu gestartet.

   Wenn Sie Ihre Lesereplikate vor dem Upgrade der primären Instanz gelöscht haben, können Sie neue Lesereplikate erstellen, die automatisch auf der aktualisierten Datenbankversion bereitgestellt werden.

3. Aktualisieren Sie die Datenbankstatistiken.

   Führen Sie ANALYZE auf der primären Instanz aus, um die Systemstatistiken nach dem Upgrade zu aktualisieren. Genaue Statistiken sorgen dafür, dass der PostgreSQL-Abfrageplaner Abfragen optimal verarbeitet. Fehlende Statistiken können zu schlechten Abfrageplänen führen, die wiederum die Leistung beeinträchtigen und zu viel Arbeitsspeicher belegen können.

4. Führen Sie Akzeptanztests durch.

   Führen Sie Tests durch, um zu prüfen, ob das aktualisierte System wie erwartet funktioniert.

Fehlerbehebung bei einem Upgrade einer Hauptversion

Cloud SQL gibt eine Fehlermeldung zurück, wenn Sie einen ungültigen Upgrade-Befehl ausführen, z. B. wenn Ihre Instanz ungültige Datenbank-Flags für die neue Version enthält.

Wenn Ihre Upgradeanfrage fehlschlägt, überprüfen Sie die Syntax der Upgradeanfrage. Wenn die Anfrage eine gültige Struktur hat, prüfen Sie die folgenden Vorschläge.

Fehler bei der Prüfung vor dem Upgrade ansehen

Fehler bei der Prüfung vor dem Upgrade sind Probleme oder Fehler, die Cloud SQL während der Überprüfung oder Validierung vor dem Upgrade erkennt. Diese Fehler treten vor dem eigentlichen Upgradeprozess auf und sollen potenzielle Probleme oder Inkompatibilitäten identifizieren, die sich auf den Erfolg des Upgrades auswirken können.

Fehler bei der Prüfung vor dem Upgrade werden für die folgenden Kategorien angezeigt:

• Inkompatible Erweiterungen: Ermitteln Sie PostgreSQL-Erweiterungen, die nicht mit der Zielversion der Instanz kompatibel sind.
• Nicht unterstützte Abhängigkeiten: Ermitteln Sie Abhängigkeiten, die nicht mehr unterstützt werden oder aktualisiert werden müssen.
• Datenformatinkompatibilitäten: Prüfen Sie Dateninkonsistenzen, die sich aus verschiedenen Faktoren ergeben, einschließlich Unterschiede bei versionsspezifischen Datenstrukturen, Änderungen bei der Codierung und Sortierung, Änderungen an Datentypen und Anpassungen am Systemkatalog.

In der folgenden Tabelle sind die Fehler bei der Prüfung vor dem Upgrade und deren Fehlermeldungen aufgeführt.

Problem mit leerem Suchpfad beheben

Das liegt daran, dass die earthdistance-Erweiterung Erd- und Würfeltypen verwendet, ohne den Suchpfad der Funktion anzugeben. Sie müssen diesen Pfad angeben, der während des Upgrades erforderlich ist.

Beheben Sie das Problem, indem Sie den Suchpfad für die Funktion ll_to_earth korrigieren. Führen Sie dazu diese Abfrage aus: ALTER FUNCTION ll_to_earth SET search_path = public;

Upgradelogs ansehen

Wenn bei einer gültigen Upgradeanfrage Probleme auftreten, veröffentlicht Cloud SQL Fehlerlogs in projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log. Jeder Logeintrag enthält ein Label mit der Instanzkennung, damit Sie die Instanz mit dem Upgradefehler identifizieren können. Suchen Sie nach solchen Upgradefehlern und beheben Sie sie.

So rufen Sie Fehlerlogs auf:

1. Wechseln Sie in der Google Cloud Console zur Seite Cloud SQL-Instanzen.

   Cloud SQL-Instanzen aufrufen

2. Klicken Sie auf den Instanznamen, um die Übersichtsseite einer Instanz zu öffnen.

3. Klicken Sie auf der Seite Übersicht der Instanz im Bereich Vorgänge und Logs auf den Link PostgreSQL-Fehlerlogs aufrufen.

   Die Seite Log-Explorer wird geöffnet.

4. So rufen Sie Logs auf:

   • Wählen Sie den Lognamen im Logfilter Logname aus, um alle Fehlerlogs in einem Projekt aufzulisten.

   Weitere Informationen zu Abfragefiltern finden Sie unter Erweiterte Abfragen.

   • Um die Upgradefehlerlogs für eine einzelne Instanz zu filtern, geben Sie die folgende Abfrage in das Feld In allen Feldern suchen ein, nachdem Sie DATABASE_ID

   durch die Projekt-ID ersetzt haben, gefolgt vom Instanznamen im folgenden Format: project_id:instance_name.

   resource.type="cloudsql_database"
   resource.labels.database_id="DATABASE_ID"
   logName : "projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

   Verwenden Sie beispielsweise den folgenden Abfragefilter, um die Upgradefehlerlogs nach einer Instanz namens shopping-db zu filtern, die im Projekt buylots ausgeführt wird:

    resource.type="cloudsql_database"
    resource.labels.database_id="buylots:shopping-db"
    logName : "projects/buylots/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

Logeinträge mit dem Präfix pg_upgrade_dump geben an, dass ein Upgradefehler aufgetreten ist. Beispiel:

pg_upgrade_dump: error: query failed: ERROR: out of shared memory
HINT: You might need to increase max_locks_per_transaction.

Darüber hinaus werden in Logeinträgen, die mit einem sekundären .txt-Dateinamen versehen sind, eventuell weitere Fehler aufgeführt, die Sie beheben sollten, bevor Sie das Upgrade wiederholen.

Alle Dateinamen finden Sie in der Datei postgres-upgrade.log. Informationen zu einem Dateinamen finden Sie im Feld labels.FILE_NAME.

Folgende Dateinamen enthalten möglicherweise Fehler, die behoben werden sollten:

• tables_with_oids.txt: Diese Datei enthält Tabellen, die mit Objekt-IDs (OIDs) aufgeführt sind. Löschen Sie die Tabellen oder ändern Sie sie so, dass sie keine OIDs verwenden.
• tables_using_composite.txt:Diese Datei enthält Tabellen, die mit vom System definierten zusammengesetzten Typen aufgelistet werden. Löschen Sie entweder die Tabellen oder ändern Sie sie so, dass sie diese zusammengesetzten Typen nicht verwenden.
• tables_using_unknown.txt: Diese Datei enthält Tabellen, die mithilfe dem Datentyp UNKNOWN aufgelistet werden. Löschen Sie die Tabellen oder ändern Sie sie so, dass sie diesen Datentyp nicht verwenden.
• tables_using_sql_identifier.txt: Diese Datei enthält Tabellen, die mithilfe dem Datentyp SQL_IDENTIFIER aufgelistet werden. Löschen Sie die Tabellen oder ändern Sie sie so, dass sie diesen Datentyp nicht verwenden.
• tables_using_reg.txt: Diese Datei enthält Tabellen, die mithilfe dem Datentyp REG* aufgelistet werden (z. B. REGCOLLATION oder REGNAMESPACE). Löschen Sie die Tabellen oder ändern Sie sie so, dass sie diesen Datentyp nicht verwenden.
• postfix_ops.txt:Diese Datei enthält Tabellen, die mit Postfix-Operatoren (rechts-unär) aufgelistet sind. Löschen Sie die Tabellen oder ändern Sie sie so, dass sie diese Operatoren nicht verwenden.

Arbeitsspeicher prüfen

Wenn die Instanz nicht genügend freigegebenen Arbeitsspeicher hat, wird möglicherweise diese Fehlermeldung angezeigt: ERROR: out of shared memory. Dieser Fehler tritt wahrscheinlich auf, wenn Sie mehr als 10.000 Tabellen haben.

Bevor Sie ein Upgrade ausführen, setzen Sie den Wert des Flags max_locks_per_transaction auf etwa die doppelte Anzahl von Tabellen in der Instanz. Die Instanz wird neu gestartet, wenn Sie den Wert dieses Flags ändern.

Verbindungskapazität prüfen

Wenn Ihre Instanz keine ausreichende Verbindungskapazität hat, wird möglicherweise diese Fehlermeldung angezeigt: ERROR: Insufficient connections.

Cloud SQL empfiehlt, den Flag-Wert max_connections um die Anzahl der Datenbanken in Ihrer Instanz zu erhöhen. Die Instanz wird neu gestartet, wenn Sie den Wert dieses Flags ändern.

Mehrdeutige Spaltenreferenz prüfen

Wenn in Ihren Ansichten eine mehrdeutige Spaltenreferenz vorhanden ist, wird möglicherweise diese Fehlermeldung angezeigt: ERROR: column reference "<column_name>" is ambiguous. Dieses Problem tritt auf, wenn durch eine neue PostgreSQL-Version Änderungen an der Struktur von Systemkatalogansichten wie pg_stat_activity und pg_stat_replication vorgenommen werden. Dies kann benutzerdefinierte Ansichten beeinträchtigen, die auf der Spaltenreihenfolge basieren.

Wenn Sie prüfen möchten, ob diese Fehlermeldung angezeigt wird, fügen Sie dem Abfrageeditor die folgende Abfrage hinzu: textPayload =~ "ERROR: column reference .+ is ambiguous at character \d+"

Sie haben folgende Möglichkeiten, dieses Problem zu beheben:

1. Benutzerdefinierte Ansichten anpassen

   Aktualisieren Sie die Spaltenreferenzen in Ihren benutzerdefinierten Ansichten, damit sie der Definition der neuen Systemkatalogansicht (z. B. pg_stat_activity und pg_stat_replication) in der Ziel-PostgreSQL-Version entsprechen.

2. Erstellen Sie Ihre Ansichten neu.

   Löschen Sie Ihre benutzerdefinierten Ansichten, bevor Sie ein Upgrade der Hauptversion ausführen. Erstellen Sie die Ansichten nach Abschluss des Upgrades neu und achten Sie darauf, dass sie mit der neuen Struktur kompatibel sind.

Ein detaillierteres Beispiel für das Problem und weitere Informationen finden Sie in dieser Stack Overflow-Diskussion.

In CASE-Anweisungen nach SRFs suchen

Wenn Sie Ihre Instanz von Version 9.6 aktualisieren und in Ihren CASE-Beschreibungen Funktionen verwenden, die Werte zurückgeben, wird möglicherweise diese FehlermeldungERROR: set-returning functions are not allowed in CASE angezeigt. Dieses Problem tritt auf, da seit Version 10 die Verwendung von Funktionen, die ein Set zurückgeben, in CASE-Anweisungen nicht mehr zulässig ist.

Um dieses Problem zu beheben und die Instanz erfolgreich zu aktualisieren, müssen alle CASE-Anweisungen, die Funktionen mit Rückgabe von Sets verwenden, so geändert werden, dass sie nicht mehr verwendet werden, bevor Sie das Upgrade noch einmal versuchen. Zu den häufig verwendeten SRFs gehören:

• unnest()
• generate_series()
• array_agg()
• regexp_split_to_table()
• jsonb_array_elements()
• json_array_elements()
• sonb_each()
• json_each()

Aufrufe von benutzerdefinierten Übertragungen prüfen

Wenn Sie eine Ansicht für eine benutzerdefinierte Übertragung erstellt haben, wird eine Fehlermeldung wie die folgende angezeigt: ERROR: cannot cast type <type_1> to <type_2>. Dieses Problem tritt aufgrund von Berechtigungsproblemen bei benutzerdefinierten Übertragungen auf.

Aktualisieren Sie Ihre Instanz auf [PostgreSQL version].R20240910.01_02, um dieses Problem zu beheben.

Weitere Informationen finden Sie unter Wartung per Selfservice.

Inhaberschaft des Ereignistriggers prüfen

Wenn der Eigentümer eines Ereignistriggers nicht die Rolle „cloudsqlsuperuser“ hat, erhalten Sie möglicherweise eine Fehlermeldung wie ERROR: permission denied to change owner of event trigger "<trigger_name>". Dieses Problem wird durch Berechtigungsprobleme beim Erstellen dieser Trigger während des Upgrades verursacht. Sie können die folgende Abfrage in den Abfrageeditor einfügen, um nach dieser Fehlermeldung zu suchen. textPayload =~ "ERROR: permission denied to change owner of event trigger .+ "

Prüfen Sie dazu die Inhaberschaft aller Ereignistrigger in Ihrer Instanz. Der Inhaber jedes Triggers muss ein cloudsqlsuperuser sein. Wenn die Trigger anderen Nutzern gehören, aktualisieren Sie die Inhaberschaft auf einen cloudsqlsuperuser, bevor Sie das Upgrade noch einmal versuchen. Mit der folgenden Abfrage können Sie die Inhaberschaft ändern: ALTER EVENT TRIGGER <trigger_name> OWNER TO <cloudsqlsuperuser>;

Mit der folgenden Abfrage können Sie eine Liste der Ereignisauslöser und die Details zum Eigentümer abrufen. SELECT evtname AS trigger_name, evtowner::regrole AS owner FROM pg_event_trigger;

Generierte Spalten aus nicht geloggten Tabellen prüfen

Wenn Sie eine nicht protokollierte Tabelle mit generierten Spalten haben, wird möglicherweise die Fehlermeldung ERROR: unexpected request for new relfilenumber in binary upgrade mode angezeigt. Dieses Problem tritt aufgrund von Abweichungen bei den Speichereigenschaften zwischen Tabellen und ihren Sequenzen für generierte Spalten auf.

So beheben Sie das Problem:

1. Löschen Sie nicht geloggte Tabellen: Löschen Sie nach Möglichkeit alle nicht geloggten Tabellen, die mit generierten Spalten verknüpft sind. Sorgen Sie dafür, dass Datenverluste sicher minimiert werden können, bevor Sie fortfahren.
2. In permanente Tabellen konvertieren: Sie können nicht protokollierte Tabellen vorübergehend in permanente Tabellen konvertieren. Gehen Sie dazu so vor:
   1. Tabelle in eine protokollierte Tabelle konvertieren ALTER TABLE SET LOGGED;
   2. Upgrade auf eine Hauptversion ausführen
   3. Tabelle wieder in eine nicht protokollierte Tabelle konvertieren ALTER TABLE SET UNLOGGED

Mit der folgenden Abfrage können Sie alle entsprechenden Tabellen ermitteln :

SELECT
  relnamespace::regnamespace,
  c.relname AS table_name,
  a.attname AS column_name,
  a.attidentity AS identity_type
FROM
  pg_catalog.pg_class c
  JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid
WHERE
  a.attidentity IN ('a', 'd') AND c.relkind = 'r' AND c.relpersistence = 'u'
ORDER BY c.relname, a.attname;

Benutzerdefinierte Flags für Ihre PostgreSQL-Instanz prüfen

Wenn Sie ein Upgrade auf eine PostgreSQL-Instanz der Version 14 oder höher ausführen, prüfen Sie die Namen der benutzerdefinierten Datenbank-Flags, die Sie für die Instanz konfiguriert haben. Dies liegt daran, dass PostgreSQL zusätzliche Einschränkungen für zulässige Namen für benutzerdefinierte Parameter platziert hat.

Das erste Zeichen eines benutzerdefinierten Datenbank-Flags muss alphabetisch (A–Z oder a–z) sein. Alle nachfolgenden Zeichen können alphanumerische Zeichen, Sonderzeichen (_) oder das Sonderzeichen Dollar ($) sein.

Erweiterungen entfernen

Wenn Sie Ihre Cloud SQL-Instanz aktualisieren, wird möglicherweise die folgende Fehlermeldung angezeigt: pg_restore: error: could not execute query: ERROR: role "16447" does not exist.

Führen Sie die folgenden Schritte aus, um das Problem zu beheben:

1. Entfernen Sie die Erweiterungen pg_stat_statements und pgstattuple.
2. Führen Sie das Upgrade aus.
3. Installieren Sie die Erweiterungen neu.

Wiederherstellung der vorherigen Hauptversion

Wenn das aktualisierte Datenbanksystem nicht wie erwartet funktioniert, müssen Sie die Instanz möglicherweise in der vorherigen Version wiederherstellen. Dazu stellen Sie die Sicherung vor dem Upgrade in einer Cloud SQL-Wiederherstellungsinstanz wieder her. Dabei handelt es sich um eine neue Instanz, auf der die Version vor dem Upgrade ausgeführt wird.

Gehen Sie so vor, um die vorherige Version wiederherzustellen:

1. Ermitteln Sie die Sicherung vor dem Upgrade.

   Siehe Automatische Upgradesicherungen.

2. Erstellen Sie eine Wiederherstellungsinstanz.

   Erstellen Sie eine neue Cloud SQL-Instanz mithilfe der Hauptversion, die Cloud SQL beim Erstellen der Sicherung vor dem Upgrade ausgeführt hat. Legen Sie dieselben Flags und Instanzeinstellungen fest wie für die ursprüngliche Instanz.

3. Stellen Sie die Sicherung vor dem Upgrade wieder her.

   Stellen Sie die Sicherung vor dem Upgrade auf der Wiederherstellungsinstanz wieder her. Die Ausführung dieses Befehls kann mehrere Minuten dauern.

4. Fügen Sie die Lesereplikate hinzu.

   Wenn Sie Lesereplikate verwendet haben, fügen Sie sie einzeln hinzu.

5. Verbinden Sie Ihre Anwendung.

   Nachdem Sie das Datenbanksystem wiederhergestellt haben, aktualisieren Sie Ihre Anwendung mit Details über die Wiederherstellungsinstanz und die zugehörigen Lesereplikate. Sie können die Verarbeitung des Traffics in der Version der Datenbank vor dem Upgrade fortsetzen.

Häufig gestellte Fragen

Bei der Aktualisierung der Hauptversion der Datenbank können die folgenden Fragen auftreten.

Ist meine Instanz während eines Upgrades nicht verfügbar?

Ja. Die Instanz ist für einen bestimmten Zeitraum nicht verfügbar, während Cloud SQL das Upgrade durchführt.

Wie lange dauert ein Upgrade?

Das Upgrade einer einzelnen Instanz dauert in der Regel weniger als 10 Minuten. Wenn Ihre Instanzkonfiguration eine kleine Anzahl von vCPUs oder Arbeitsspeicher verwendet, kann das Upgrade länger dauern.

Wenn Ihre Instanz zu viele Datenbanken oder Tabellen hostet oder Ihre Datenbanken sehr groß sind, kann das Upgrade Stunden dauern oder sogar eine Zeitüberschreitung erfolgen, da die Upgradezeit der Anzahl der Objekte in Ihren Datenbanken entspricht. Wenn Sie mehrere Instanzen aktualisieren müssen, wird die Gesamtupgradedauer proportional erhöht.

Kann ich die einzelnen Schritte in meinem Upgrade-Prozess überwachen?

Mit Cloud SQL können Sie zwar beobachten, ob ein Upgradevorgang noch läuft, Sie können jedoch nicht die einzelnen Schritte in jedem Upgrade verfolgen.

Kann ich mein Upgrade nach dem Start abbrechen?

Nein, Sie können ein Upgrade nicht mehr abbrechen, nachdem es gestartet wurde. Wenn Ihr Upgrade fehlschlägt, stellt Cloud SQL Ihre Instanz automatisch mit der vorherigen Version wieder her.

Was geschieht mit meinen Einstellungen während eines Upgrades?

Wenn Sie ein direktes Upgrade der Hauptversion durchführen, behält Cloud SQL Ihre Datenbankeinstellungen bei, einschließlich Instanzname, IP-Adresse, explizit konfigurierte Flag-Werte und Nutzerdaten bei. Der Standardwert der Systemvariablen kann sich jedoch ändern. Der Standardwert des Flags password_encryption in PostgreSQL 13 und früheren Versionen ist beispielsweise md5. Wenn Sie ein Upgrade auf PostgreSQL 14 durchführen, ändert sich der Standardwert dieses Flags in scram-sha-256.

Weitere Informationen finden Sie unter Datenbank-Flags konfigurieren. Wenn ein bestimmtes Flag oder ein Wert in Ihrer Zielversion nicht mehr unterstützt wird, entfernt Cloud SQL das Flag während des Upgrades automatisch.

Nächste Schritte

• Informationen über die Verbindungsoptionen einer Instanz
• Weitere Informationen über das Importieren und Exportieren von Daten
• Datenbank-Flags festlegen