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.

Beim Cloud SQL-Vorgang für das direkte Upgrade von PostgreSQL wird das Dienstprogramm pg_upgrade verwendet.

Upgrade einer Hauptversion planen

  1. Prüfen Sie, ob Sie die erforderliche Rolle für ein Upgrade der Hauptversion haben: Cloud SQL-Inhaber oder Cloud SQL-Administrator.

  2. 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:
      2. 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:

    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:

    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.

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

    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.

  4. Führen Sie die Vorabprüfung für Upgrades durch.

  5. 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.

  6. 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.

    Eine weitere Möglichkeit ist, die Datenbank umzubenennen:

    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 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. Dadurch kann das Upgrade blockiert werden. Informationen zum Beheben dieses Problems finden Sie unter Fehlerhafte PostGIS-Rasterinstallation beheben.

    Manchmal kann ein Upgrade auf PostGIS-Version 3.1.7 oder höher nicht abgeschlossen werden, weil Objekte veraltete Funktionen verwenden. Dadurch kann das Upgrade blockiert werden. Führen Sie SELECT PostGIS_full_version(); aus, um den Upgradestatus 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 beliebige Zwischen- oder höhere Version. Führen Sie den Befehl SELECT PostGIS_full_version(); dann noch einmal aus. Prüfen Sie, ob 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.
  3. 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.
  4. 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.
  5. 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 der Hauptversion auf PostgreSQL 16 und höher durchführen, müssen Sie die PostGIS-Erweiterung für alle Ihre Datenbanken auf Version 3.4.0 aktualisieren. Für PostgreSQL 18 müssen Sie ein Upgrade auf PostGIS-Version 3.6.0 durchführen.
  • Bevor Sie ein direktes Upgrade der Hauptversion auf PostgreSQL 17 durchführen, müssen Sie die rdkit-Erweiterung für alle Ihre Datenbanken auf Version 4.6.1 aktualisieren.
  • Bevor Sie ein direktes Hauptversions-Upgrade auf PostgreSQL 16, 17 oder 18 durchführen, müssen Sie die Erweiterung pg_squeeze für alle Ihre Datenbanken auf Version 1.6, 1.7 bzw. 1.8 aktualisieren.
  • Wenn Sie PostgreSQL-Version 9.6, 10, 11 oder 12 verwenden, wird Version 3.4.0 der PostGIS-Erweiterung nicht unterstützt. Wenn Sie also ein In-Place-Hauptversionsupgrade auf PostgreSQL 16 und höher durchführen möchten, müssen Sie zuerst ein Upgrade auf eine Zwischenversion von PostgreSQL (Version 13, 14 oder 15) durchführen.

  • Wenn Sie die Erweiterung pg_ivm für Ihre Instanz installieren, können Sie kein Upgrade der Hauptversion durchführen. Deinstallieren Sie die Erweiterung und führen Sie dann das Upgrade durch, um das Problem zu beheben. 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 durchführen. Löschen Sie diese Flags und führen Sie dann das Upgrade durch, um das Problem zu beheben. Weitere Informationen zu den Flags, einschließlich des Löschens von Flags, finden Sie unter Datenbank-Flags konfigurieren.

Bereitschaft für das Upgrade Ihrer Instanz prüfen

Mit Cloud SQL können Sie vor einem Upgrade der Hauptversion eine Vorabprüfung für Ihre Instanz ausführen. Diese Vorabprüfung ist ein Vorgang mit langer Ausführungszeit, bei dem geprüft wird, ob Ihre Instanz für ein Upgrade bereit ist. So lassen sich potenzielle Probleme wie Inkompatibilitäten, Konfigurationsprobleme oder Datenprobleme vor dem Upgrade erkennen.

Bei der Vorabprüfung wird entweder bestätigt, dass Ihre Instanz aktualisiert werden kann, oder es werden Probleme aufgeführt, die Sie zuerst beheben müssen, sowie die entsprechenden Lösungen. Diese Probleme können durch inkompatible Erweiterungen, nicht unterstützte Abhängigkeiten oder Probleme mit dem Datenformat verursacht werden.

Beim Vorabcheck werden hauptsächlich die Metadaten Ihrer Instanz gelesen und Prüfungen durchgeführt. Diese Aufgaben haben keine Auswirkungen auf die Leistung Ihrer Instanz und führen nicht zu Ausfallzeiten. Wir empfehlen dringend, die Vorabprüfung auszuführen, da sie dazu beiträgt, Fehler bei der Aktualisierung und unerwartete Ausfallzeiten zu vermeiden.

Wenn Sie die Vorabprüfung ausführen, geschieht Folgendes:

  • Keine Probleme gefunden: Die Vorabprüfung wurde erfolgreich abgeschlossen und es wurden keine Probleme gefunden.
  • Probleme, die das Upgrade blockieren, wurden gefunden: Die Vorabprüfung wurde erfolgreich abgeschlossen, es wurden jedoch Fehler gefunden, die das Upgrade verhindern. Die Probleme müssen vor dem Upgrade behoben werden.
  • Nicht blockierende Warnungen gefunden: Die Vorabprüfung wurde erfolgreich abgeschlossen und es wurden Warnungen gefunden, aber keine davon verhindert das Upgrade.

Je nach Ergebnis der Vorabprüfung können Sie entweder mit dem Upgrade fortfahren oder die ermittelten Probleme vor dem Upgrade beheben.

Beschränkungen

Beachten Sie bei der Verwendung der Vorabprüfung für das Upgrade auf die Hauptversion die folgenden Einschränkungen:

  • Der Instanzstatus muss auf RUNNING gesetzt sein.
  • Die Instanz muss eine primäre Instanz sein. Replikate werden von „precheck“ nicht unterstützt.

  • Für die Instanz dürfen keine blockierenden Vorgänge ausstehen. Wenn ein blockierender Vorgang aussteht, führt die Vorabprüfung zu einem Fehler mit der folgenden Meldung:

    Operation failed because another operation was already in progress. Try
your request after the current operation is complete.

  • Für die Vorabprüfung muss eine Verbindung zu allen Datenbanken in der Instanz hergestellt werden. Wenn eine Datenbank nicht zugänglich, gesperrt oder nicht reaktionsfähig ist, kann die Vorabprüfung fehlschlagen oder Fehler anzeigen. Die Vorabprüfung hat zwar keine Auswirkungen auf die Leistung Ihrer Instanz und führt auch nicht zu Ausfallzeiten, wir empfehlen jedoch, sie bei geringer Datenbanklast auszuführen.

Hinweise

  • Achten Sie darauf, dass die Cloud SQL Admin API für Ihre Instanz aktiviert ist.
  • Prüfen Sie, ob Sie die cloudsql.instances.preCheckMajorVersionUpgrade IAM-Berechtigung haben.

Vorabprüfung durchführen

So führen Sie die Vorabprüfung für das Upgrade auf die Hauptversion durch:

gcloud

  1. Führen Sie die Vorabprüfung aus:

    gcloud sql instances pre-check-major-version-upgrade INSTANCE_NAME \
--target-database-version=TARGET_DATABASE_VERSION \
--project=PROJECT_ID \
[--async]

    Ersetzen Sie Folgendes:

    • INSTANCE_NAME: der Name der Instanz.
    • TARGET_DATABASE_VERSION: Die Hauptversion, auf die Sie Ihre Instanz aktualisieren möchten. Informationen zum Ermitteln der Datenbankversion finden Sie unter Upgrade planen.
    • PROJECT_ID: die ID Ihres Google Cloud Projekts.

  2. Rufen Sie den Namen des Pre-Check-Vorgangs ab:

    Führen Sie den Befehl gcloud sql operations list mit dem Flag --instance aus:

    gcloud sql operations list --instance=INSTANCE_NAME

    Ersetzen Sie Folgendes:

    • INSTANCE_NAME: der Name der Instanz.

  3. Überwachen Sie den Status der Vorabprüfung.

    Führen Sie den Befehl gcloud sql operations describe aus:

    gcloud sql operations describe OPERATION_NAME

    Ersetzen Sie Folgendes:

    • OPERATION_NAME: Der Name des Vorabprüfvorgangs, der im vorherigen Schritt abgerufen wurde.

REST Version 1

  1. Führen Sie die Vorabprüfung durch.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • PROJECT_ID: die Projekt-ID
    • INSTANCE_ID: die Instanz-ID
    • TARGET_DATABASE_VERSION: Die Hauptversion, auf die aktualisiert werden soll. Eine Liste der verfügbaren Datenbankversionen finden Sie unter Upgrade planen.

    HTTP-Methode und URL: 

    POST https://sqladmin.googleapis.com/sql/v1b/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

    JSON-Text anfordern:

    {
  "preCheckMajorVersionUpgradeContext": {
    "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
  }
}

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

    Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

    {
  "message": "Precheck description of finding",
  "message_type": "ERROR",
  "actions_required": [
    "Precheck action required to fix the finding"
  ]
}

  2. Rufen Sie den Namen des Pre-Check-Vorgangs ab.

    Verwenden Sie die GET-Anfrage mit der Methode operations.list, nachdem Sie PROJECT_ID durch die ID des Projekts ersetzt haben.

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die ID Ihres Google Cloud Projekts.

  3. Überwachen Sie den Status der Vorabprüfung.

    Verwenden Sie die GET-Anfrage mit der Methode operations.list:

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die ID Ihres Google Cloud Projekts.
    • OPERATION_NAME: Der Name des Vorabprüfvorgangs, der im vorherigen Schritt abgerufen wurde.

REST v1beta4

  1. Führen Sie die Vorabprüfung durch.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • PROJECT_ID: die Projekt-ID
    • INSTANCE_ID: die Instanz-ID
    • TARGET_DATABASE_VERSION: Die Hauptversion, auf die aktualisiert werden soll. Eine Liste der verfügbaren Datenbankversionen finden Sie unter Upgrade planen.

    HTTP-Methode und URL: 

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

    JSON-Text anfordern:

    {
  "preCheckMajorVersionUpgradeContext": {
    "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
  }
}

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

    Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

    {
  "message": "Precheck description of finding",
  "message_type": "ERROR",
  "actions_required": [
    "Precheck action required to fix the finding"
  ]
}

  2. Rufen Sie den Namen des Pre-Check-Vorgangs ab.

    Verwenden Sie die GET-Anfrage mit der Methode operations.list, nachdem Sie PROJECT_ID durch die ID des Projekts ersetzt haben.

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die ID Ihres Google Cloud Projekts.

  3. Überwachen Sie den Status der Vorabprüfung.

    Verwenden Sie die GET-Anfrage mit der Methode operations.list:

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die ID Ihres Google Cloud Projekts.
    • operation_name: Der Name des Vorabprüfvorgangs, der im vorherigen Schritt abgerufen wurde.

Ergebnisse der Vorabprüfung ansehen

Nach Abschluss der Vorabprüfung ist Ihre Instanz entweder bereit für das Upgrade oder es sind Probleme aufgetreten, die behoben werden müssen.

Bereit für Upgrade

Wenn die Vorabprüfung erfolgreich abgeschlossen wurde und das preCheckResponse-Array leer ist, wurden keine Probleme oder Warnungen gefunden. Ihre Instanz ist bereit für das Upgrade auf eine Hauptversion. Weitere Informationen finden Sie unter Hauptversionsupgrade durchführen.

Nicht bereit für das Upgrade

Wenn die Vorabprüfung erfolgreich ausgeführt wurde und das preCheckResponse-Array Probleme enthält, ist Ihre Instanz nicht für das Upgrade bereit und muss überprüft werden. Die identifizierten Probleme können das Upgrade blockieren, müssen es aber nicht. Diese Probleme werden in preCheckResponse mit den folgenden Nachrichtentypen angegeben:

Typ Beschreibung Blockiert Upgrade?
INFO Eine Nachricht zur Information. Nein
WARNING Es wurde ein potenzielles Problem gefunden, das das Upgrade jedoch nicht blockiert. Cloud SQL empfiehlt, die Warnung vor dem Upgrade zu prüfen und zu beheben, um die vollständige Kompatibilität zu gewährleisten. Nein
ERROR Es wurde ein kritisches Problem gefunden, das das Upgrade blockiert. Diese Probleme können dazu führen, dass das Upgrade fehlschlägt. Sie müssen diese Probleme beheben, bevor Sie Ihre Instanz aktualisieren. Ja

Wenn Ihre Instanz nur INFO- oder WARNING-Nachrichten enthält, können Sie sie aktualisieren. Nach dem Upgrade können jedoch Probleme auftreten. Wir empfehlen, die Details der Meldung zu prüfen und das Problem zu beheben, bevor Sie das Upgrade durchführen. Wenn Ihre Instanz ERROR Meldungen enthält, müssen Sie diese Probleme beheben, bevor Sie ein Upgrade durchführen.

Jeder Problemtyp enthält ein message- und ein actions_required-Feld. Sehen Sie sich jedes Problem an, um den Typ und die Lösung zu ermitteln. Weitere Informationen zu häufigen Problemen und deren Lösungen finden Sie unter Häufige Fehler bei der Vorabprüfung für das Upgrade der Hauptversion.

Nachdem Sie die Probleme behoben haben, führen Sie den Vorabcheck noch einmal aus, um zu bestätigen, dass Ihre Instanz für das Upgrade bereit ist. Fahren Sie dann mit dem Upgrade Ihrer Instanz fort, sobald die Vorabprüfung abgeschlossen ist.

Upgrade der Hauptversion durchführen

Sie können die Hauptversion einer einzelnen Cloud SQL-Instanz oder die Hauptversion einer primären Instanz aktualisieren und alle zugehörigen Replikate in das Upgrade einbeziehen, einschließlich kaskadierender Replikate und regionenübergreifender Replikate.

Hauptversion einer einzelnen Instanz aktualisieren

Wenn Sie einen Upgradevorgang für eine einzelne Instanz starten, führt Cloud SQL die folgenden Schritte aus:

  1. Prüft die Konfiguration Ihrer Instanz, um sicherzustellen, dass die Instanz für ein Upgrade kompatibel ist.
  2. Nachdem Cloud SQL die Konfiguration geprüft hat, wird die Instanz von Cloud SQL deaktiviert.
  3. Erstellt eine Sicherung vor dem Upgrade.
  4. Führt das Upgrade auf der Instanz aus.
  5. Stellt Ihre Instanz zur Verfügung.
  6. Erstellt eine Sicherung nach dem Upgrade.

Console

  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 Bearbeiten.
  4. Klicken Sie im Abschnitt Instanzinformationen auf die Schaltfläche Upgrade und bestätigen Sie, dass Sie die Seite "Upgrade" aufrufen möchten.
  5. Klicken Sie auf der Seite Datenbankversion auswählen auf die Liste Datenbankversion für Upgrade und wählen Sie eine der verfügbaren Hauptversionen der Datenbank aus.
  6. Klicken Sie auf Weiter.
  7. Geben Sie im Feld Instanz-ID den Namen der Instanz ein und klicken Sie dann auf die Schaltfläche Upgrade starten.
Der Vorgang kann mehrere Minuten dauern.

Prüfen Sie, ob die Hauptversion der aktualisierten Datenbank unter dem Instanznamen auf der Seite Übersicht der Instanz angezeigt wird.

gcloud

  1. Starten Sie das Upgrade.

    Führen Sie den Befehl gcloud sql instances patch mit dem Flag --database-version aus.

    Ersetzen Sie vor dem Ausführen des Befehls Folgendes:

    • INSTANCE_NAME: Name der Instanz
    • DATABASE_VERSION: Der Enum für die Hauptversion der Datenbank, der höher als die aktuelle Version sein muss. Geben Sie eine Datenbankversion für eine Hauptversion an, die als Upgrade-Ziel für die Instanz verfügbar ist. Sie können diesen Enum als ersten Schritt von Upgrade planen abrufen. Eine vollständige Liste der Enums für Datenbankversionen finden Sie unter SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
--database-version=DATABASE_VERSION

    Upgrades von Hauptversionen dauern einige Minuten. Möglicherweise wird eine Meldung angezeigt, die angibt, dass der Vorgang länger als erwartet dauert. Sie können diese Nachricht entweder ignorieren oder den Befehl gcloud sql operations wait ausführen, um sie zu verwerfen.

  2. Rufen Sie den Namen des Upgradevorgangs ab.

    Führen Sie den Befehl gcloud sql operations list mit dem Flag --instance aus.

    Bevor Sie den Befehl ausführen, ersetzen Sie die Variable INSTANCE_NAME durch den Namen der Instanz. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. Überwachen Sie den Status des Upgrades.

    Führen Sie folgenden Befehl gcloud sql operations describe aus.

    Bevor Sie den Befehl ausführen, ersetzen Sie die Variable OPERATION durch den Namen des Upgradevorgangs, der im vorherigen Schritt abgerufen wurde. 

    gcloud sql operations describe OPERATION

REST Version 1

  1. Starten Sie das direkte Upgrade.

    Verwenden Sie eine PATCH-Anfrage mit der Methode instances:patch.

    Ersetzen Sie diese Variablen, bevor Sie die Anfragedaten verwenden:

    • PROJECT_ID: ID des Projekts
    • INSTANCE_NAME: Name der Instanz

    HTTP-Methode und URL:

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

    JSON-Text anfordern:

    {
  "databaseVersion": DATABASE_VERSION
}

    Ersetzen Sie DATABASE_VERSION durch den Enum der Hauptversion der Datenbank. Dieser muss höher als die aktuelle Version sein. Geben Sie eine Datenbankversion für eine Hauptversion an, die als Upgrade-Ziel für die Instanz verfügbar ist. Sie können diesen Enum als ersten Schritt von Upgrade planen abrufen. Eine vollständige Liste der Enums für Datenbankversionen finden Sie unter SqlDatabaseVersion.

  2. Rufen Sie den Namen des Upgradevorgangs ab.

    Verwenden Sie eine GET-Anfrage mit der Methode operations.list, nachdem Sie PROJECT_ID durch die ID des Projekts ersetzt haben.

    HTTP-Methode und URL:

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

  3. Überwachen Sie den Status des Upgrades.

    Verwenden Sie eine GET-Anfrage mit der Methode operations.get, nachdem Sie die folgenden Variablen ersetzt haben:

    • PROJECT_ID: ID des Projekts
    • OPERATION_NAME: Der Name des Upgradevorgangs, der im vorherigen Schritt abgerufen wurde.

    HTTP-Methode und URL:

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

Terraform

Verwenden Sie zum Aktualisieren der Version der Datenbank eine Terraform-Ressource und den Terraform-Anbieter für Google Cloud, Version 4.34.0 oder höher.

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
}

Änderungen anwenden

Führen Sie die Schritte in den folgenden Abschnitten aus, um Ihre Terraform-Konfiguration auf ein Google Cloud -Projekt anzuwenden.

Cloud Shell vorbereiten

  1. Rufen Sie Cloud Shell auf.

  2. Legen Sie das Standardprojekt Google Cloud fest, auf das Sie Ihre Terraform-Konfigurationen anwenden möchten.

    Sie müssen diesen Befehl nur einmal pro Projekt und in jedem beliebigen Verzeichnis ausführen.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Umgebungsvariablen werden überschrieben, wenn Sie in der Terraform-Konfigurationsdatei explizite Werte festlegen.

Verzeichnis vorbereiten

Jede Terraform-Konfigurationsdatei muss ein eigenes Verzeichnis haben (auch als Stammmodul bezeichnet).

  1. Erstellen Sie in Cloud Shell ein Verzeichnis und eine neue Datei in diesem Verzeichnis. Der Dateiname muss die Erweiterung .tf haben, z. B. main.tf. In dieser Anleitung wird die Datei als main.tf bezeichnet. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Wenn Sie einer Anleitung folgen, können Sie den Beispielcode in jedem Abschnitt oder Schritt kopieren.

    Kopieren Sie den Beispielcode in das neu erstellte main.tf.

    Kopieren Sie optional den Code aus GitHub. Dies wird empfohlen, wenn das Terraform-Snippet Teil einer End-to-End-Lösung ist.

  3. Prüfen und ändern Sie die Beispielparameter, die auf Ihre Umgebung angewendet werden sollen.
  4. Speichern Sie die Änderungen.
  5. Initialisieren Sie Terraform. Dies ist nur einmal für jedes Verzeichnis erforderlich. 
    terraform init

    Fügen Sie optional die Option -upgrade ein, um die neueste Google-Anbieterversion zu verwenden: 

    terraform init -upgrade

Änderungen anwenden

  1. Prüfen Sie die Konfiguration und prüfen Sie, ob die Ressourcen, die Terraform erstellen oder aktualisieren wird, Ihren Erwartungen entsprechen: 
    terraform plan

    Korrigieren Sie die Konfiguration nach Bedarf.

  2. Wenden Sie die Terraform-Konfiguration an. Führen Sie dazu den folgenden Befehl aus und geben Sie yes an der Eingabeaufforderung ein: 
    terraform apply

    Warten Sie, bis Terraform die Meldung „Apply complete“ anzeigt.

  3. Öffnen Sie Ihr Google Cloud Projekt, um die Ergebnisse aufzurufen. Rufen Sie in der Google Cloud Console Ihre Ressourcen in der Benutzeroberfläche auf, um sicherzustellen, dass Terraform sie erstellt oder aktualisiert hat.

Änderungen löschen

So löschen Sie das Projekt:

  1. Um den Löschschutz zu deaktivieren, setzen Sie in der Terraform-Konfigurationsdatei das Argument deletion_protection auf false. 
    deletion_protection =  "false"
  2. Wenden Sie die aktualisierte Terraform-Konfiguration an. Führen Sie dazu den folgenden Befehl aus und geben Sie yes an der Eingabeaufforderung ein: 
    terraform apply

  1. Entfernen Sie Ressourcen, die zuvor mit Ihrer Terraform-Konfiguration angewendet wurden, indem Sie den folgenden Befehl ausführen und yes an der Eingabeaufforderung eingeben:

    terraform destroy

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.

Replikate in das Upgrade der Hauptversion einbeziehen

Wenn Ihre primäre Instanz Replikate hat, können Sie alle Replikate in das Upgrade einbeziehen. Cloud SQL kann alle Replikate der primären Instanz aktualisieren, einschließlich regionenübergreifender Replikate und kaskadierender Replikate.

Wenn Sie Replikate in ein Upgrade der Hauptversion einbeziehen, führt Cloud SQL die folgenden Schritte aus:

  1. Prüft die Konfiguration Ihrer primären Instanz und der Replikate, um sicherzustellen, dass die Instanz und die Replikate für ein Upgrade kompatibel sind.
  2. Dadurch wird Ihre primäre Instanz nicht mehr verfügbar.
  3. Erstellt eine Sicherung der primären Instanz vor dem Upgrade.
  4. Die Replikation wird für alle Replikate beendet.
  5. Führt das Upgrade auf der primären Instanz durch.
  6. Wenn das Upgrade der primären Instanz erfolgreich ist, wird die primäre Instanz wieder verfügbar und die Replikation wird neu gestartet.
  7. Cloud SQL erstellt eine Sicherung der primären Instanz nach dem Upgrade.
  8. Cloud SQL führt ein Upgrade aller Replikate durch.

Auch wenn das Upgrade der Hauptversion eines Replikats fehlschlägt, bleibt die primäre Instanz verfügbar.

Wenn Sie Replikate in ein Upgrade der Hauptversion einbeziehen möchten, können Sie dieGoogle Cloud Console oder Terraform nicht verwenden. Sie können nur die gcloud CLI oder die Cloud SQL Admin API verwenden.

gcloud

  1. Starten Sie das Upgrade.

    Verwenden Sie den gcloud sql instances patch-Befehl mit den Flags --database-version und --include-replicas-for-major-version-upgrade.

    Ersetzen Sie vor dem Ausführen des Befehls Folgendes:

    • INSTANCE_NAME: Der Name der primären Instanz.
    • DATABASE_VERSION: Der Enum für die Hauptversion der Datenbank, der höher als die aktuelle Version sein muss. Geben Sie eine Datenbankversion für eine Hauptversion an, die als Upgrade-Ziel für die Instanz verfügbar ist. Sie können diesen Enum als ersten Schritt von Upgrade planen abrufen. Eine vollständige Liste der Enums für Datenbankversionen finden Sie unter SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
  --database-version=DATABASE_VERSION \
  --include-replicas-for-major-version-upgrade

    Upgrades von Hauptversionen dauern einige Minuten. Möglicherweise wird eine Meldung angezeigt, die angibt, dass der Vorgang länger als erwartet dauert. Sie können diese Nachricht entweder ignorieren oder den Befehl gcloud sql operations wait ausführen, um sie zu verwerfen. Das Aktualisieren von Replikaten kann mehrere Minuten dauern. So prüfen Sie den Status des Upgrades:

  2. Rufen Sie den Namen des Upgradevorgangs ab.

    Führen Sie den Befehl gcloud sql operations list mit dem Flag --instance aus.

    Bevor Sie den Befehl ausführen, ersetzen Sie die Variable INSTANCE_NAME durch den Namen der Instanz. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. Überwachen Sie den Status des Upgrades.

    Führen Sie folgenden Befehl gcloud sql operations describe aus.

    Bevor Sie den Befehl ausführen, ersetzen Sie die Variable OPERATION durch den Namen des Upgradevorgangs, der im vorherigen Schritt abgerufen wurde. 

    gcloud sql operations describe OPERATION

REST

  1. Starten Sie das direkte Upgrade.

    Verwenden Sie eine PATCH-Anfrage mit der Methode instances:patch.

    Ersetzen Sie diese Variablen, bevor Sie die Anfragedaten verwenden:

    • PROJECT_ID: ID des Projekts
    • INSTANCE_NAME: Name der Instanz

    HTTP-Methode und URL:

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

    JSON-Text anfordern:

    {
  "databaseVersion": DATABASE_VERSION
  "includeReplicasForMajorVersionUpgrade": true
}

    • Ersetzen Sie DATABASE_VERSION durch den Enum der Hauptversion der Datenbank. Dieser muss höher als die aktuelle Version sein. Geben Sie eine Datenbankversion für eine Hauptversion an, die als Upgrade-Ziel für die Instanz verfügbar ist. Sie können diesen Enum als ersten Schritt von Upgrade planen abrufen. Eine vollständige Liste der Enums für Datenbankversionen finden Sie unter SqlDatabaseVersion.
    • Geben Sie im Feld includeReplicasForMajorVersionUpgrade den Wert true ein.

  2. Rufen Sie den Namen des Upgradevorgangs ab.

    Verwenden Sie eine GET-Anfrage mit der Methode operations.list, nachdem Sie PROJECT_ID durch die ID des Projekts ersetzt haben.

    HTTP-Methode und URL:

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

  3. Überwachen Sie den Status des Upgrades.

    Verwenden Sie eine GET-Anfrage mit der Methode operations.get, nachdem Sie die folgenden Variablen ersetzt haben:

    • PROJECT_ID: ID des Projekts
    • OPERATION_NAME: Der Name des Upgradevorgangs, der im vorherigen Schritt abgerufen wurde.

    HTTP-Methode und URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

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 dem Upgrade der primären Instanz die folgenden Schritte aus, um das Upgrade abzuschließen:

  1. 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.

  2. 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-Logs 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: Google Cloud

  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"

    Sie können entweder alle Logs ansehen, die in einem bestimmten Zeitraum gemeldet wurden, oder Logs nach Schweregrad filtern. Eine gängige Option zur Fehlerbehebung ist die Auswahl der folgenden Filter:

    • Notfall
    • Benachrichtigung
    • Kritisch
    • Fehler

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.

Auf mehrdeutige Spaltenverweise prüfen

Cloud SQL führt automatisch eine Vorabprüfung durch, um nutzerdefinierte Ansichten zu identifizieren, die von Systemkatalogansichten wie pg_stat_activity oder pg_stat_replication abhängen. Die Spaltenstruktur dieser Systemkatalogansichten kann sich zwischen den PostgreSQL-Hauptversionen ändern. Wenn Sie Ansichten haben, die select * oder auf der Spaltenreihenfolge dieser Systemansichten basieren, sind sie nach einem Upgrade möglicherweise nicht mehr kompatibel. Das kann zu einem Fehler wie ERROR: column reference "column_name" is ambiguous führen.

Bei der Prüfung vor dem Upgrade werden solche Ansichten durch die Suche nach Abhängigkeiten erkannt. Wenn inkompatible Ansichten gefunden werden, wird der Aktualisierungsvorgang beendet und eine Fehlermeldung angezeigt. In dieser Meldung werden die inkompatiblen Ansichten in jeder Datenbank aufgeführt, die behoben werden müssen.

Beispiel für Fehlermeldung

  • Bei Problemen mit pg_stat_activity: 

    Please remove the following usages of views that depend on functions returning
data types of pg_stat_activity before attempting an upgrade:
(database: my_db, schema name: public, view name: my_stat_activity_view)

  • Bei Problemen mit pg_stat_replication:

    Please remove the following usages of views that depend on functions returning
data types of pg_stat_replication before attempting an upgrade:
(database: my_db, schema name: public, view name: my_replication_stats_view)

So beheben Sie solche Probleme und fahren mit dem Upgrade fort: 1. Ermitteln Sie die Ansichten, die in der Fehlermeldung der Prüfung vor dem Upgrade aufgeführt sind.

  1. Löschen Sie diese Ansichten mit DROP VIEW view_name;.

  2. Wiederholen Sie das Upgrade der Hauptversion.

  3. Erstellen Sie die Ansichten nach Abschluss des Upgrades neu. Prüfen Sie, ob die neuen Ansichtsdefinitionen mit dem Schema der Systemkatalogansichten in der aktuellen PostgreSQL-Version kompatibel sind. Möglicherweise müssen Sie Spalten explizit auflisten, anstatt select * zu verwenden, um zukünftige Probleme zu vermeiden.

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

Nach SRFs in CASE-Anweisungen suchen

Wenn Sie Ihre Instanz von Version 9.6 aktualisieren und mengenorientierte Funktionen in Ihren CASE-Anweisungen verwenden, wird möglicherweise die Fehlermeldung ERROR: set-returning functions are not allowed in CASE angezeigt. Dieses Problem tritt ab Version 10 auf, da die Verwendung von Funktionen, die Mengen zurückgeben, in CASE-Anweisungen nicht zulässig ist.

Um dieses Problem zu beheben und Ihre Instanz erfolgreich zu aktualisieren, müssen Sie alle CASE-Anweisungen, in denen mengenwertige Funktionen verwendet werden, so ändern, dass sie nicht mehr verwendet werden. Versuchen Sie dann noch einmal, das Upgrade durchzuführen. Einige häufig verwendete SRFs sind:

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

Aufrufe von benutzerdefinierten Streams prüfen

Wenn Sie eine Ansicht für einen benutzerdefinierten Cast 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 Casts auf.

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

Weitere Informationen finden Sie unter Self-Service-Wartung.

Inhaberschaft von Ereignistriggern prüfen

In Cloud SQL müssen alle Ereignistrigger einem Nutzer mit der Rolle cloudsqlsuperuser gehören. Cloud SQL führt eine Prüfung vor dem Upgrade durch, um die Inhaberschaft aller Ereignistrigger zu validieren. Wenn ein Ereignistrigger einem Nutzer gehört, der nicht die Rolle cloudsqlsuperuser hat, wird der Upgradevorgang angehalten und Sie erhalten möglicherweise eine Fehlermeldung wie:

Please ensure that the owners of all event triggers have the cloudsqlsuperuser
role assigned to them before attempting an upgrade:
(database: your_db, triggerName your_trigger, owner: non_super_user)

Um dieses Problem zu beheben, ändern Sie entweder den Inhaber des Ereignistriggers zu einem Nutzer mit der Rolle cloudsqlsuperuser, z. B. postgres, oder weisen Sie dem aktuellen Inhaber die Rolle cloudsqlsuperuser zu.

Führen Sie den folgenden Befehl aus, um Ereignistrigger mit Inhabern zu ermitteln, die nicht die erforderliche Rolle haben:

SELECT
  t.evtname AS trigger_name,
  r.rolname AS current_owner
FROM pg_event_trigger t
JOIN pg_roles r ON t.evtowner = r.oid
WHERE NOT pg_has_role(r.rolname, 'cloudsqlsuperuser', 'member');

In den Ergebnissen werden alle Ereignistrigger mit einem Inhaber angezeigt, der nicht die Rolle cloudsqlsuperuser hat.

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 Persistenzmerkmalen zwischen Tabellen und ihren Sequenzen für generierte Spalten auf.

So beheben Sie das Problem:

  1. Nicht geloggte Tabellen löschen: Löschen Sie nach Möglichkeit alle nicht geloggten Tabellen, die mit generierten Spalten verknüpft sind. Stellen Sie sicher, dass Datenverlust sicher vermieden werden kann, bevor Sie fortfahren.
  2. In permanente Tabellen konvertieren: Konvertieren Sie unprotokollierte Tabellen vorübergehend in permanente Tabellen. Gehen Sie dazu so vor:
    1. Tabelle in eine protokollierte Tabelle konvertieren ALTER TABLE SET LOGGED;
    2. Upgrade der Hauptversion durchführen
    3. Tabelle wieder in eine nicht protokollierte Tabelle umwandeln ALTER TABLE SET UNLOGGED

Sie können alle diese Tabellen mit der folgenden Abfrage 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.

MVU-Vorgang mit langer Ausführungszeit

Mit einem Upgrade auf eine Hauptversion sind zwei zugrunde liegende Aufgaben verbunden:

  • Vorabprüfung: Gibt einen Zeitüberschreitungsfehler zurück, wenn sie nicht innerhalb von drei Stunden abgeschlossen ist.
  • Upgradevorgang: Gibt einen Zeitüberschreitungsfehler zurück, wenn er nicht innerhalb von sechs Stunden abgeschlossen wird.

Wenn für die Instanz ein MAJOR_VERSION_UPGRADE-Vorgang läuft, der länger als erwartet dauert, prüfen Sie die PostgreSQL-Fehlerlogs. Das kann folgende Ursachen haben:

  • Eine große Anzahl von Tabellen, Ansichten oder Indexen
  • Unzureichende Ressourcen wie CPU oder Arbeitsspeicher
  • Wichtige Transaktionen verhindern das Herunterfahren von Datenbanken, damit der Aktualisierungsprozess beginnen kann. Sie können die Google Cloud Console verwenden, um aktuelle Prozesse zu prüfen.

Häufige Fehler bei der Vorabprüfung für das Upgrade einer Hauptversion

Probleme, die bei der Vorabprüfung für das Upgrade der Hauptversion gefunden werden, fallen in diese Kategorien:

  • Inkompatible Erweiterungen: Dies sind Cloud SQL for PostgreSQL-Erweiterungen in Ihrer Instanz, die nicht mit der neuen Hauptversion funktionieren.

  • Nicht unterstützte Abhängigkeiten: Das sind Abhängigkeiten, die entweder von der neuen Hauptversion nicht unterstützt werden oder für die Updates erforderlich sind, damit sie damit funktionieren.

  • Datenbankinkompatibilitäten: Dies sind Probleme mit Ihrer Datenbank oder Ihren Daten, die nach einem Upgrade auf eine neue Hauptversion auftreten können. Dazu gehören Unterschiede bei Datenbankstrukturen, Datentypen, Codierung, Sortierung oder Änderungen am Systemkatalog, die für die neue Version spezifisch sind.

Inkompatible Erweiterungen

In der folgenden Tabelle sind häufige Fehler im Zusammenhang mit inkompatiblen Erweiterungen aufgeführt, die bei der Vorabprüfung für das Upgrade auf die Hauptversion gefunden werden können:

Typ Fehlerbeispiel Lösung
Nicht unterstützte oder eingestellte Erweiterung Your installation contains unsupported extensions for the new version. These extensions must be removed before attempting an upgrade: (database: %s, Extension name: %s) Entfernen Sie die Erweiterung aus allen Datenbanken, in denen sie mit DROP EXTENSION $extension_name; verwendet wird.
Inkompatible Erweiterungsversion Your installation contains incompatible version extensions. These extensions must be upgraded to a compatible version before attempting an upgrade: (database: %s, Extension name: %s) Aktualisieren Sie die Erweiterung auf eine Version, die mit Ihrer Zielversion von Cloud SQL for PostgreSQL funktioniert. Informationen zu kompatiblen Versionen finden Sie unter Cloud SQL for PostgreSQL-Erweiterungen konfigurieren.
PostGIS entpackte Dateien PostGIS version upgrade has not been completed, unpackaged raster files present. Follow the steps at https://postgis.net/documentation/tips/tip-removing-raster-from-2-3/ to fix before major version upgrade. Bereinigen Sie die entpackten Rasterdateien.
PostGIS eingestellte Funktionen PostGIS version upgrade has not been completed, deprecated functions present. Please drop all objects using deprecated functions and upgrade to a different version of PostGIS before major version upgrade. Suchen Sie alle Datenbankobjekte, in denen die eingestellten PostGIS-Funktionen verwendet werden, und entfernen oder ändern Sie sie, bevor Sie die PostGIS-Erweiterung aktualisieren.
Inhaberschaft von Erweiterungen Please ensure that the owner of the postgres_fdw extension has the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: my_db, extension name: postgres_fdw, owner: some_user) Ändern Sie den Inhaber der Erweiterung mit ALTER EXTENSION postgres_fdw OWNER TO postgres;.

Nicht unterstützte Abhängigkeiten

In der folgenden Tabelle sind häufige Fehler im Zusammenhang mit nicht unterstützten Abhängigkeiten aufgeführt, die bei der Vorabprüfung für das Upgrade auf die Hauptversion gefunden werden können:

Typ Fehlerbeispiel Lösung
Inhaberschaft von Ereignistriggern Please ensure that the owners of all event triggers have the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: your_db, triggerName your_trigger, owner: non_super_user) Stellen Sie mit psql oder Cloud SQL Studio eine Verbindung zur ermittelten Datenbank her und ändern Sie den Inhaber des Triggers in einen postgres-Nutzer.
Nicht festgeschriebene vorbereitete Anweisungen Please commit/rollback the following usages of 'Uncommitted Prepared Statements'... (database: my_db, gid: my_prepared_xact) Führen Sie entweder ein Commit oder ein Rollback für die vorbereitete Anweisung aus.
Verworfene Flags flag "force_parallel_mode" is deprecated in new postgres version, Please delete this flag before retrying again Entfernen Sie das Datenbank-Flag aus der Instanzkonfiguration.

Datenbankinkompatibilitäten

In der folgenden Tabelle sind häufige Fehler im Zusammenhang mit Inkompatibilitäten des Datenformats aufgeführt, die bei der Vorabprüfung für das Upgrade der Hauptversion gefunden werden können:

Typ Fehlerbeispiel Lösung
Unbekannter Datentyp Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) Entfernen Sie die Spalte oder Tabelle oder ändern Sie den Datentyp der Tabelle mit ALTER TABLE my_table ALTER COLUMN my_column TYPE TEXT;.
Datentyp reg* Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) Entfernen Sie die Spalte oder ändern Sie ihren Datentyp.
Entfernter Datentyp Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: ... Konvertieren Sie die Daten in TEXT, timestamptz oder einen anderen geeigneten Datentyp.
​​aclitem Internes Format Please remove the following usages of 'aclitem' data types before attempting an upgrade: ... Verwenden Sie aclitem nicht mehr in den Definitionen Ihrer Datenbanktabellen.
Systemdefinierte zusammengesetzte Datentypen Please remove the following usages of 'composite' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) Ändern Sie die erkannten Spalten so, dass ein benutzerdefinierter zusammengesetzter Typ oder ein Standarddatentyp verwendet wird. Zusammengesetzte Systemtypen sind möglicherweise nicht über alle Hauptversionen hinweg konsistent.
Tabellen mit OIDS Please remove the following usages of tables with OIDs before attempting an upgrade: (database: my_db, relation: my_table) Aktualisieren Sie die Tabelle mit ALTER TABLE my_table SET WITHOUT OIDS;.
Benutzerdefinierte postfix-Operatoren Please remove the following usages of 'postfix operators' before attempting an upgrade: (database: my_db, operation id: 12345, operation namespace: public, operation name: !!, type namespace: public, type name: mytype) Entfernen Sie die benutzerdefinierten postfix-Operatoren. Möglicherweise müssen Sie Ihren Code umschreiben, um stattdessen Präfixoperatoren oder Funktionsaufrufe zu verwenden.
Inkompatible polymorphe Funktionen Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: my_db, object kind: function, object name: public.my_poly_func) Entfernen oder ändern Sie die Funktion, um inkompatible polymorphe Funktionen zu entfernen. Das kann bedeuten, dass Sie Funktionssignaturen oder ‑logik anpassen müssen, damit sie mit Cloud SQL for PostgreSQL 14 und höher funktionieren.
Benutzerdefinierte Codierungskonvertierungen Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: my_db, namespace name: public, encoding conversions name: my_encoding_conv) Entfernen Sie die benutzerdefinierte Codierungskonvertierung. Möglicherweise müssen Sie sie nach dem Upgrade mit einer Signatur neu erstellen, die mit der neuen Version funktioniert.
Auf mehrdeutige Spaltenverweise prüfen Cloud SQL sucht automatisch nach benutzerdefinierten Ansichten, die auf Systemkatalogansichten basieren. Die Spaltenstruktur dieser Systemkatalogansichten kann sich zwischen Hauptversionen ändern.

Please remove the following usages of views that depend on functions returning data types of pg_stat_activity before attempting an upgrade: (database: my_db, schema name: public, view name: my_stat_activity_view) 		Suchen Sie die in der Fehlermeldung aufgeführten Ansichten und entfernen Sie sie mit dem Befehl DROP VIEW. Erstellen Sie die Ansichten nach dem Upgrade neu.
Nicht geloggte Tabellen mit generierten Spalten oder geloggten Sequenzen Please drop the following usages of 'Unlogged Tables with Logged Sequence' before attempting an upgrade: (database: your_db, table name: problematic_table) Sie können die Tabelle entweder in LOGGED konvertieren oder sie mit dem Befehl DROP TABLE entfernen. Erstellen Sie die Tabelle nach dem Upgrade neu.
Problem mit leerem Suchpfad beheben Please update the search path of the 'll_to_earth' function (database: your_db, search path: ) Die Erweiterung earthdistance verwendet earth und cube types, ohne den Suchpfad der Funktion anzugeben. Aktualisieren Sie den Suchpfad mit ALTER FUNCTION ll_to_earth SET search_path = public;.

Primäre Instanz auf die vorherige Hauptversion zurücksetzen

Wenn das aktualisierte Datenbanksystem nicht wie erwartet funktioniert, müssen Sie die primäre 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.

So stellen Sie eine primäre Instanz auf die vorherige Version wieder her:

  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 verwenden, 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 gesamte Upgradezeit der Anzahl der Objekte in Ihren Datenbanken entspricht. Wenn Sie mehrere Instanzen aktualisieren müssen, wird die Upgradedauer proportional erhöht. Wenn Sie Replikate in Ihr Upgrade einbeziehen, kann das Upgrade je nach Anzahl der Replikate Ihrer primären Instanz bis zu einer Stunde dauern.

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