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 auf eine neue 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 eine JSON-Antwort ähnlich wie diese 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 eine JSON-Antwort ähnlich wie diese 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 aus.

  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 ein Upgrade während eines Zeitraums, wenn die Datenbankaktivität niedrig ist. Wir empfehlen, ein Upgrade der Hauptversion nicht in Zeiten mit hohem Traffic oder bei aktiven, lang andauernden Transaktionen in Ihrer Datenbank durchzuführen.

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 besteht darin, die Datenbank umzubenennen:

    1. Schließen Sie alle Verbindungen zur Datenbank.
    2. Benennen Sie die Datenbank um.
    3. Aktualisieren Sie Ihre Anwendungskonfigurationen, um den neuen Datenbanknamen zu verwenden.
    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. Dies kann den Upgradevorgang blockieren. 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. Dies kann den Upgradevorgang blockieren. 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 verworfenen Funktionen verwenden, und aktualisieren Sie die PostGIS-Erweiterung auf eine Zwischen- oder höhere Version. Führen Sie nach Abschluss dieser Aktionen den Befehl SELECT PostGIS_full_version(); 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().

  6. Instanzen mit einer großen Anzahl von Objekten verwalten.

    Die für ein direktes Upgrade der Hauptversion erforderliche Zeit hängt von der Anzahl der Datenbankobjekte in der Instanz ab. Bei Instanzen mit einer sehr großen Anzahl von Objekten, insbesondere Tabellen und Indexen, kann das Upgrade erheblich länger dauern. Dadurch erhöht sich das Risiko, dass der Vorgang das Zeitlimit überschreitet. Cloud SQL ist für Instanzen mit bis zu etwa 100.000 Beziehungen optimiert. Wenn Ihre Instanz diesen Wert überschreitet, wird das Upgrade nicht blockiert, aber es gilt als weniger zuverlässig und dauert wahrscheinlich länger oder schlägt nach einer Zeitüberschreitung von 6 Stunden fehl.

    Wenn Ihre Instanz eine große Anzahl von Objekten enthält, gehen Sie vor dem Start des Hauptupgrades so vor:

    1. Nicht verwendete Objekte prüfen und löschen: Identifizieren und entfernen Sie alle leeren Tabellen, Tabellen, die nur zu Testzwecken verwendet werden, oder andere Datenbankobjekte (Schemas, Ansichten, Funktionen), die nicht mehr benötigt werden.
    2. Tabellenstrukturen optimieren:
      • Wenn Sie die Tabellenpartitionierung verwenden, kann eine übermäßige Anzahl von Partitionen zu einer hohen Anzahl von Relationen beitragen. In diesem Fall sollten Sie prüfen, wie Sie die Anzahl der verwendeten Partitionen reduzieren können.
      • Sie können Verlaufsdaten oder Daten, auf die selten zugegriffen wird, zu einer anderen Datenspeicheroption migrieren. Dadurch kann sich die Anzahl der aktiven Tabellen oder die Größe und Komplexität vorhandener Tabellen verringern.
    3. Führen Sie einen Upgradetest aus: Führen Sie einen Probelauf des Upgrades für einen Klon Ihrer Produktionsinstanz aus. So erhalten Sie eine realistische Schätzung der erforderlichen Zeit und können potenzielle Probleme erkennen. Diese Schätzung ist besonders wichtig für Datenbanken mit einer hohen Anzahl von Objekten.

    Durch die Reduzierung der Gesamtzahl und Komplexität der Objekte können Sie die Risiken und Ausfallzeiten im Zusammenhang mit Upgrades auf Hauptversionen verringern.

  7. Instanzen mit Large Objects (LOBs) verwalten

    Beim direkten Upgrade wird das PostgreSQL-Dienstprogramm pg_upgrade verwendet. Dieser Vorgang kann sehr lange dauern, wenn die Datenbank eine sehr große Anzahl von LOBs enthält. Dies kann zu einem Upgrade-Fehler aufgrund einer Zeitüberschreitung führen.

    Wenn Sie die Anzahl der Large Objects in Ihrer Datenbank prüfen möchten, stellen Sie mit einem PostgreSQL-Client wie psql eine Verbindung zu Ihrer Datenbankinstanz her und führen Sie die folgende Abfrage aus:

        SELECT count(*) AS total_large_objects FROM pg_largeobject_metadata;

    Wenn Ihre Instanz mehr als 30 Millionen LOBs enthält, besteht ein erhöhtes Risiko für eine Zeitüberschreitung. In solchen Fällen sollten Sie vor dem Start eines Upgrades die folgenden Maßnahmen in Betracht ziehen:

    1. Verwaiste Large Objects bereinigen: PostgreSQL entfernt LOBs, auf die nicht mehr verwiesen wird, nicht automatisch. Verwenden Sie das Dienstprogramm vacuumlo, das Teil des Moduls contrib ist, um verwaiste LOBs zu entfernen. Sie müssen diesen Befehl auf einem Clientcomputer ausführen, der eine Verbindung zu Ihrer Cloud SQL-Instanz herstellen kann.
      • Installieren Sie das Paket postgresql-contrib auf Ihrem Clientcomputer, wenn Sie vacuumlo nicht haben.
      • Führen Sie den folgenden Befehl aus, um einen Probelauf durchzuführen und zu sehen, welche LOBs gelöscht werden würden: 
                vacuumlo -h INSTANCE_IP -U DATABASE_USER --dry-run DATABASE_NAME
        Ersetzen Sie INSTANCE_IP, DATABASE_USER und DATABASE_NAME durch Ihre Instanzdetails. Sie werden aufgefordert, das Passwort des Nutzers einzugeben.
      • Führen Sie den folgenden Befehl aus, um die identifizierten LOBs zu entfernen: 
                vacuumlo -h INSTANCE_IP -U DATABASE_USER DATABASE_NAME
        Prüfen Sie nach dem Ausführen von vacuumlo noch einmal die Anzahl der LOBs, um zu bestätigen, dass die Bereinigung erfolgreich war.
    2. Große Objekte manuell löschen: Prüfen Sie die Richtlinien zur Datenaufbewahrung Ihrer Anwendung und entfernen Sie alle LOBs, die nicht mehr erforderlich sind.
    3. Instanzressourcen erhöhen: Erhöhen Sie vorübergehend oder dauerhaft die vCPUs und den Arbeitsspeicher der Instanz. Dadurch stehen dem pg_upgrade-Prozess mehr Ressourcen zur Verfügung.
    4. Daten migrieren: Wenn die Anzahl der LOBs nicht ausreichend reduziert werden kann, sollten Sie ein Upgrade durch Migrieren Ihrer Daten in Betracht ziehen. Sie können mit pg_dump und pg_restore einen benutzerdefinierten Ansatz speziell für LOBs erstellen. Standardmethoden für die logische Replikation unterstützen LOBs möglicherweise nicht vollständig. Für die LOB-Migration sind dann eventuell zusätzliche Schritte und Ausfallzeiten erforderlich.

  8. Notieren Sie sich die Informationen, die Sie benötigen, um alle logischen Replikationsslots auf der Instanz neu zu erstellen, einschließlich der Slots, die von pglogical, der integrierten logischen Replikation von PostgreSQL, Datastream oder einem anderen logischen Decodierungs-Consumer verwendet werden.

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.
  • Verwenden Sie die Anweisung select * from pg_largeobject_metadata;, um die Anzahl der großen Objekte in jeder PostgreSQL-Datenbank Ihrer Cloud SQL-Instanz abzufragen. 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-Hauptversionsupgrade auf PostgreSQL 16 und höher durchführen, aktualisieren Sie die PostGIS-Erweiterung für alle Ihre Datenbanken auf Version 3.4.0. Führen Sie für PostgreSQL 18 ein Upgrade auf PostGIS-Version 3.6.0 durch.
  • Bevor Sie ein direktes Upgrade der Hauptversion auf PostgreSQL 17 durchführen, aktualisieren Sie die Erweiterung rdkit für alle Ihre Datenbanken auf Version 4.6.1.
  • Bevor Sie ein direktes Upgrade der Hauptversion auf PostgreSQL 16, 17 oder 18 durchführen, aktualisieren Sie die Erweiterung pg_squeeze für alle Ihre Datenbanken auf Version 1.6, 1.7 oder 1.8.
  • Wenn Sie die PostgreSQL-Versionen 9.6, 10, 11 oder 12 verwenden, wird die Version 3.4.0 der PostGIS-Erweiterung nicht unterstützt. Wenn Sie ein direktes Hauptversionsupgrade auf PostgreSQL 16 oder 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 diese 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 aus, um das Problem zu beheben. Weitere Informationen zu den Flags, einschließlich des Löschens, finden Sie unter Datenbank-Flags konfigurieren.

Upgradebereitschaft für Ihre Instanz prüfen

Mit Cloud SQL können Sie vor einem Upgrade der Hauptversion eine Vorabprüfung Ihrer 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 können Sie potenzielle Probleme wie Inkompatibilitäten, Konfigurationsprobleme oder Datenprobleme vor dem Upgrade erkennen.

Die Vorabprüfung bestätigt entweder, dass Ihre Instanz aktualisiert werden kann, oder listet Probleme auf, die Sie zuerst beheben müssen, und deren Lösungen. Diese Probleme können auf inkompatible Erweiterungen, nicht unterstützte Abhängigkeiten oder Probleme mit dem Datenformat zurückzuführen sein.

Cloud SQL kann die Vorabprüfung parallel zu Ihrer Arbeitslast ausführen. Wenn Sie die Vorabprüfung vor dem Upgrade einer Hauptversion ausführen, können Sie einen Upgradefehler verhindern.

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 gefunden: Die Vorabprüfung wurde erfolgreich abgeschlossen, es wurden jedoch Fehler gefunden, die das Upgrade blockieren. Die Probleme müssen vor dem Upgrade behoben werden.
  • Warnungen gefunden: Die Vorabprüfung wurde erfolgreich abgeschlossen und es wurden Warnungen gefunden. Prüfen Sie die Warnungen. Wir empfehlen, alle Probleme zu beheben, bevor Sie mit dem Upgrade fortfahren.

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

Beschränkungen

Beachten Sie bei der Vorabprüfung des Upgrades auf die Hauptversion die folgenden Einschränkungen:

  • Der Instanzstatus muss auf RUNNING festgelegt sein.
  • Die Instanz muss eine primäre Instanz sein. Die Vorabprüfung unterstützt keine Replikatinstanzen.

  • 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 reagiert, kann die Vorabprüfung fehlschlagen oder Fehler anzeigen. Wir empfehlen, die Vorabprüfung auszuführen, wenn die Datenbanklast niedrig ist.

Hinweis

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

Vorabprüfung durchführen

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

Console

  1. Rufen Sie in der Google Cloud Console die Seite Cloud SQL-Instanzen auf.

    Cloud SQL-Instanzen aufrufen

  2. Suchen Sie die Instanz, für die Sie die Vorabprüfung durchführen möchten. Klicken Sie auf den Instanznamen, um die Übersichtsseite der Instanz zu öffnen.
  3. Klicken Sie auf Bearbeiten.
  4. Klicken Sie unter Instanzinformationen auf Upgrade validieren.
  5. Wählen Sie im Dialogfeld Upgrade validieren die Datenbankversion aus, auf die Sie ein Upgrade durchführen möchten, und klicken Sie dann auf Validieren.

    Die Vorprüfung beginnt. Beobachten Sie den Status der Vorabprüfung in der Benachrichtigungsleiste Vorgänge.

  6. Nach Abschluss der Vorabprüfung wird ein neues Fenster mit dem Namen Upgrade-Ergebnisse validieren geöffnet. Dieses Fenster enthält die Ergebnisse der Vorprüfung. Die Ergebnisse können eine der folgenden sein:
    • Wenn die Vorabprüfung keine Fehler enthält, klicken Sie auf Seite aktualisieren, um den Upgradevorgang zu starten.
    • Wenn die Vorabprüfung info-Nachrichten enthält, sehen Sie sich die Ergebnisse an. Wenn Sie bereit für das Upgrade sind, klicken Sie auf Seite aktualisieren, um den Upgradeprozess zu starten.
    • Wenn die Vorabprüfung warning-Meldungen enthält, prüfen Sie die Ergebnisse. Wir empfehlen, diese Warnungen zu beheben, bevor Sie mit dem Upgrade fortfahren. Diese Meldungen blockieren den Upgradevorgang jedoch nicht.
    • Wenn der Vorabprüfungsvorgang errors enthält, prüfen Sie die Ergebnisse. Beheben Sie die Fehler und führen Sie die Vorabprüfung dann noch einmal aus. Alle Fehler müssen behoben werden, bevor Sie mit dem Upgrade beginnen.

gcloud

  1. Verwenden Sie gcloud sql instances pre-check-major-version-upgrade, um die Vorabprüfung auszuführen:

    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 Projekts in Google Cloud .

    Optional: Verwenden Sie das Flag --async, um den Befehl asynchron auszuführen.

  2. Wenn Sie das Flag --async verwenden, um den Befehl pre-check-major-version-upgrade asynchron auszuführen, gehen Sie so vor:

    1. Rufen Sie den Namen des Vorabprüfungsvorgangs ab:

      Verwenden Sie den Befehl gcloud sql operations list mit dem Flag --instance:

      gcloud sql operations list --instance=INSTANCE_NAME

      Ersetzen Sie Folgendes:

      • INSTANCE_NAME: der Name der Instanz.

    2. Ü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üfungsvorgangs, der im vorherigen Schritt abgerufen wurde.
  3. Wenn Sie den Befehl pre-check-major-version-upgrade nicht asynchron ausführen, warten Sie, bis die Vorabprüfung abgeschlossen ist, um die Ergebnisse anzusehen.

REST Version 1

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

    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/v1/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 Vorabprüfungsvorgangs 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 Projekts in Google Cloud .

  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 Projekts in Google Cloud .
    • OPERATION_NAME: Der Name des Vorabprüfungsvorgangs, der im vorherigen Schritt abgerufen wurde.

REST v1beta4

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

    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 das Upgrade durchgeführt 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 Vorabprüfungsvorgangs 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/sql/v1beta4/projects/PROJECT_ID/operations

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die ID Ihres Projekts in Google Cloud .

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

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

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

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die ID Ihres Projekts in Google Cloud .
    • operation_name: Der Name des Vorabprüfungsvorgangs, 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 gibt Probleme, die Ihre Aufmerksamkeit erfordern.

Bereit für Upgrade

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

Nicht bereit für Upgrade

Wenn die Vorabprüfung erfolgreich ausgeführt wurde und das Array preCheckResponse Probleme enthält, ist Ihre Instanz nicht für das Upgrade bereit und muss überprüft werden. Die erkannten Probleme können das Upgrade blockieren oder auch nicht. Diese Probleme werden in der preCheckResponse mit den folgenden Nachrichtentypen vermerkt:

Typ Beschreibung Blockiert Upgrade?
INFO Eine Informationsnachricht. 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 ein Upgrade Ihrer Instanz durchführen. Ja
Wenn Ihre Instanz nur INFO- oder WARNING-Nachrichten hat, können Sie sie aktualisieren, aber nach dem Upgrade können Probleme auftreten. Wir empfehlen, die Nachrichtendetails zu prüfen und das Problem vor dem Upgrade zu beheben. Wenn Ihre Instanz ERROR-Nachrichten hat, müssen Sie diese Probleme vor dem Upgrade beheben.

Jeder Problemtyp enthält ein message- und ein actions_required-Feld. Sehen Sie sich die einzelnen Probleme an, um den Typ und die Lösung zu verstehen. Weitere Informationen zu häufigen Problemen und deren Lösungen finden Sie unter Häufige Fehler bei der Vorabprüfung des Hauptversionsupgrades.

Führen Sie nach dem Beheben der Probleme die Vorabprüfung noch einmal aus, um zu bestätigen, dass Ihre Instanz für das Upgrade bereit ist. Fahren Sie dann mit dem Upgrade der Instanz fort, sobald die Vorabprüfung abgeschlossen ist.

Upgrade der Hauptversion durchführen

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

Upgrade der Hauptversion einer einzelnen Instanz durchführen

Wenn Sie einen Upgradevorgang für eine einzelne Instanz starten, führt Cloud SQL Folgendes 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 überprüft hat, wird die Instanz 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. Rufen Sie in der Google Cloud Console die Seite Cloud SQL-Instanzen auf.

    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 den Button 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 den Button 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.

    Ersetzen Sie vor dem Ausführen des Befehls Folgendes: * INSTANCE_NAME: der Name 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

Wenn Sie die Hauptversion der Datenbank mit Terraform aktualisieren möchten, müssen Sie das Argument database_version in der Definition der google_sql_database_instance-Ressource auf die Zielhauptversion festlegen. Sie müssen den Terraform-Anbieter für Google Cloud Version 4.34.0 oder höher verwenden.

Die folgenden Beispiele zeigen eine einfache google_sql_database_instance-Konfiguration. Wenn Sie ein Upgrade der Hauptversion durchführen möchten, setzen Sie das Argument database_version auf die entsprechende Hauptversion.

resource "google_sql_database_instance" "default" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
  }
}

Nehmen Sie die folgenden Änderungen an den Terraform-Argumenten vor:

  • database_version: Legen Sie hier die Zielhauptversion für das Upgrade fest.
  • deletion_protection: Definiert die Terraform-Schutzmaßnahme auf Stammebene gegen das Löschen von Instanzen.
    • true: Verhindert, dass Terraform die Instanz löscht. Alle Terraform-Vorgänge, die das Löschen dieser Ressource vorsehen, werden blockiert.
    • false: Erlaubt Terraform, die Instanz zu löschen.

Terraform-Plan prüfen

Führen Sie vor dem Anwenden von Änderungen immer terraform plan aus und prüfen Sie die Ausgabe sorgfältig. Die Symbole neben dem Ressourcennamen geben an, wie Terraform die Änderungen anwendet:

  • ~ Direkt aktualisieren: Dieses Symbol gibt an, dass Terraform die vorhandene Instanz ändert. Dies ist das erwartete und sichere Ergebnis für ein direktes Upgrade der Hauptversion, wenn database_version geändert wird.
  • +/- Neu erstellen (Ersatz erzwingen): Dieses Symbol bedeutet, dass Terraform die aktuelle Instanz löschen und eine neue erstellen wird.
    • Wenn deletion_protection auf true gesetzt ist, gibt Terraform einen Fehler aus und blockiert diesen gefährlichen Ersatz. Sie müssten deletion_protection = false explizit in Ihrer Konfiguration festlegen und terraform apply noch einmal ausführen, um den Status zu aktualisieren, bevor ein nachfolgender apply das Löschen und Neuerstellen zulässt.
    • Wenn deletion_protection auf false gesetzt ist, würde terraform apply mit dem Datenverlust fortfahren.

    Instanzen können aufgrund einer Konfigurationsänderung oder eines nicht unterstützten Upgradepfads für eine direkte Änderung zum Ersetzen (Löschen und Neuerstellen) geplant werden. Wenn Sie feststellen, dass eine Instanz gelöscht und neu erstellt werden soll, sollten Sie den Vorgang sofort beenden und den Grund für den geplanten Austausch untersuchen, bevor er fortgesetzt wird.

Prüfen Sie die Ausgabe von terraform plan, um sicherzustellen, dass nur ein In-Place-Update (~) für die Änderung der Datenbankversion angezeigt wird. Wenden Sie dann die Konfiguration an:

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

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 regionsübergreifender Replikate und kaskadierender Replikate.

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

  1. Prüft die Konfiguration Ihrer primären Instanz und Replikate, um sicherzustellen, dass die Instanz und die Replikate für ein Upgrade kompatibel sind.
  2. Macht die primäre Instanz nicht 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 aus.
  6. Wenn das Upgrade auf der primären Instanz erfolgreich ist, ist 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 aktualisiert alle Replikate.

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

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

gcloud

  1. Starten Sie das Upgrade.

    Verwenden Sie den Befehl gcloud sql instances patch 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 Upgrade von Replikaten kann einige 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: die ID des Projekts.
    • INSTANCE_NAME: der 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 die Option true an.

  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: die 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 abbrechen

Sie können ein direktes Upgrade einer Hauptversion abbrechen, aber nur, während die Instanz das eigentliche Versionsupgrade ausführt.

Stornierungszeitraum

Ein Upgrade auf eine Hauptversion umfasst eine Reihe von Schritten. Sie können nur während der Hauptupgradephase abbrechen.

  1. Initialisierung: Cloud SQL bereitet die Instanz und ihre Ressourcen vor. In dieser Phase können Sie nicht kündigen.

  2. Hauptupgradephase: Cloud SQL aktualisiert Ihre Daten aktiv auf die neue Hauptversion. Sie können nur während dieser Phase abbrechen.

  3. Abschluss: Die Instanz schließt das Upgrade ab und führt die letzten Prüfungen durch.

Wenn Sie wissen möchten, wann Ihre Instanz in die Phase eingetreten ist, in der das Upgrade abgebrochen werden kann, prüfen Sie, ob Upgrade-Logs verfügbar sind. Upgrade-Logs sind unter projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log verfügbar.

Wenn Logeinträge in dieser Logdatei angezeigt werden, ist die Hauptupgradephase aktiv und Sie können den Vorgang abbrechen.

Kündigung durchführen

Wenn Sie ein direktes Upgrade der Hauptversion abbrechen möchten, benötigen Sie die ID des Vorgangs. Sie müssen diese ID im gcloud- oder REST API-Befehl angeben, damit Cloud SQL weiß, welcher Vorgang abgebrochen werden soll.

Sie können die gcloud- oder REST API-Befehle verwenden, um ein Upgrade der Hauptversion abzubrechen.

gcloud

  1. Rufen Sie die Vorgangs-ID des Upgrades 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.

  2. Upgrade abbrechen.

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

    gcloud sql operations cancel OPERATION_ID

    Ersetzen Sie Folgendes:

    • OPERATION_ID: die im vorherigen Schritt abgerufene Vorgangs-ID.

  3. Prüfen Sie den Status „Abgebrochen“.

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

    gcloud sql operations describe OPERATION_ID

    Ersetzen Sie Folgendes:

    • OPERATION_ID: die Vorgangs-ID, die im ersten Schritt abgerufen wurde.

REST Version 1

  1. Rufen Sie die Vorgangs-ID des Upgrades 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 Projekts in Google Cloud .

  2. Upgrade abbrechen.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • PROJECT_ID: die ID Ihres Projekts in Google Cloud .
    • OPERATION_ID: die im vorherigen Schritt abgerufene Vorgangs-ID.

    HTTP-Methode und URL: 

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID/cancel

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

    Sie sollten eine JSON-Antwort erhalten, die in etwa so aussieht:

    Dieser REST API-Aufruf gibt keine Antwort zurück.

  3. Prüfen Sie den Status „Abgebrochen“.

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

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

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die ID Ihres Projekts in Google Cloud .
    • OPERATION_ID: die Vorgangs-ID, die im ersten Schritt abgerufen wurde.

REST v1beta4

  1. Rufen Sie die Vorgangs-ID des Upgrades 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/v1beta4/projects/PROJECT_ID/operations

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die ID Ihres Projekts in Google Cloud .

  2. Upgrade abbrechen.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: die ID Ihres Projekts in Google Cloud .
  • OPERATION_ID: die im vorherigen Schritt abgerufene Vorgangs-ID.

HTTP-Methode und URL: 

POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID/cancel

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

Sie sollten eine JSON-Antwort erhalten, die in etwa so aussieht:

Dieser REST API-Aufruf gibt keine Antwort zurück.

  1. Prüfen Sie den Status „Abgebrochen“.

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

    GET https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die ID Ihres Projekts in Google Cloud .
    • OPERATION_ID: die Vorgangs-ID, die im ersten Schritt abgerufen wurde.

Wenn Ihre Abbruchanfrage akzeptiert wird, beendet Cloud SQL den laufenden Upgradeprozess und beginnt, Ihre Instanz in den ursprünglichen Zustand zurückzusetzen.

Fehlerbehebung bei Kündigung

Problem Fehlerbehebung

Fehlermeldung: The operation OPERATION_ID cannot be canceled at the moment. Please retry in approximately 5-10 minutes

 Das Upgrade kann noch nicht storniert werden. Warten Sie einige Minuten und versuchen Sie dann noch einmal, die Bestellung zu stornieren.

Fehlermeldung: The operation OPERATION_ID cannot be cancelled as it has passed the cancellable state. The operation is in its final stage and should complete soon.

 Das Upgrade kann nicht mehr abgebrochen werden. Ein Abbruch ist nicht mehr möglich und das Upgrade sollte in Kürze abgeschlossen sein.

Fehlermeldung: You can't cancel operation OPERATION_ID because it isn't in progress.

 Der Vorgang wurde bereits abgeschlossen, entweder erfolgreich oder mit einem Fehler, und kann nicht mehr abgebrochen werden.

Fehlermeldungen

  • You can't cancel operation OPERATION_ID because Cloud SQL doesn't support the cancellation of this OPERATION_TYPE operation.
  • The operation OPERATION_ID cannot be cancelled.
 Dieser Fehler tritt normalerweise auf, wenn Sie den falschen OPERATION_ID an den Abbruchbefehl übergeben, insbesondere die ID eines Vorgangstyps, der den Abbruch nicht unterstützt. Prüfen Sie, ob Sie die OPERATION_ID verwenden, die mit dem direkten Upgrade der Datenbank-Hauptversion verknüpft ist, das Sie abbrechen möchten.

Wenn der Abbruch nach Annahme der Abbruchanfrage fehlgeschlagen ist, sollten Sie Ihre Instanz aus der Sicherung vor dem Upgrade wiederherstellen, die zu Beginn des Prozesses automatisch erstellt wurde. Wenn das Problem weiterhin besteht, wenden Sie sich an den Google Cloud -Support.

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.

  3. Um Unterbrechungen der Replikationsstreams zu vermeiden, erstellen Sie die logischen Replikationsslots Ihrer Instanz mit den Informationen, die Sie vor dem Upgrade aufgezeichnet haben (siehe Upgrade auf eine Hauptversion vorbereiten).

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.

Verwenden Sie die Google CloudConsole, um Fehlerlogs aufzurufen:

  1. Rufen Sie in der Google Cloud Console die Seite Cloud SQL-Instanzen auf.

    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 prüfen, die innerhalb eines bestimmten Zeitraums 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 mehrdeutigen Spaltenverweis prüfen

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

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

Beispiel für Fehlermeldung

  • Bei Problemen im Zusammenhang 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 im Zusammenhang 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. Achten Sie darauf, dass 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 detaillierteres Beispiel für das Problem und weitere Informationen finden Sie in dieser Stack Overflow-Diskussion.

SRFs in CASE-Anweisungen prüfen

Wenn Sie ein Upgrade Ihrer Instanz von PostgreSQL 9.6 durchführen und in Ihren CASE-Anweisungen Funktionen verwenden, die Sätze zurückgeben, wird möglicherweise die Fehlermeldung ERROR: set-returning functions are not allowed in CASE angezeigt. Dieses Problem tritt auf, weil ab Version 10 die Verwendung von Funktionen, die Sätze zurückgeben, in CASE-Anweisungen nicht mehr zulässig ist.

Um dieses Problem zu beheben und Ihre Instanz erfolgreich zu aktualisieren, müssen Sie alle CASE-Anweisungen, die set-returning-Funktionen verwenden, so ändern, dass sie nicht mehr verwendet werden, bevor Sie das Upgrade noch einmal versuchen. Zu den am häufigsten 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 Casts prüfen

Wenn Sie eine Ansicht für eine benutzerdefinierte Umwandlung 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 Umwandlungen 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 des Ereignisauslösers 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 Ereignis-Trigger 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 in einen 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 identifizieren, 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 Ereignis-Trigger mit einem Inhaber angezeigt, der nicht die Rolle cloudsqlsuperuser hat.

Generierte Spalten aus nicht protokollierten 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.

Folgen Sie dieser Anleitung, um das Problem zu beheben:

  1. Nicht protokollierte Tabellen löschen: Löschen Sie nach Möglichkeit alle nicht protokollierten 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 nicht protokollierte 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

Mit der folgenden Abfrage können Sie alle diese Tabellen identifizieren :

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 ein Upgrade Ihrer Cloud SQL-Instanz durchführen, 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 der Hauptversion sind zwei grundlegende Aufgaben verbunden:

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

Wenn die Instanz einen laufenden MAJOR_VERSION_UPGRADE-Vorgang hat, der länger als erwartet dauert, prüfen Sie die PostgreSQL-Fehlerlogs. Dies kann folgende Ursachen haben:

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

Häufige Fehler bei der Vorabprüfung von Upgrades auf Hauptversionen

Probleme, die bei der Vorabprüfung des Upgrades der Hauptversion gefunden werden, fallen in die folgenden Kategorien:

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

  • Nicht unterstützte Abhängigkeiten: Dies sind Abhängigkeiten, die entweder von der neuen Hauptversion nicht unterstützt werden oder aktualisiert werden müssen, um mit ihr zu funktionieren.

  • Datenbankinkompatibilitäten: Dies sind Probleme mit Ihrer Datenbank oder Ihren Daten, die nach einem Upgrade der 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 des Upgrades der Hauptversion gefunden werden können:

Typ Fehlerbeispiel Lösung
Nicht unterstützte oder veraltete 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 mit DROP EXTENSION $extension_name; aus allen Datenbanken, in denen sie 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 Cloud SQL for PostgreSQL-Zielversion kompatibel ist. Informationen zu kompatiblen Versionen finden Sie unter Cloud SQL for PostgreSQL-Erweiterungen konfigurieren.
PostGIS nicht verpackte 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 nicht gepackten 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 und entfernen oder ändern Sie alle Datenbankobjekte, die verworfene PostGIS-Funktionen verwenden, bevor Sie die PostGIS-Erweiterung aktualisieren.
Inhaberschaft der Erweiterung 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 des Upgrades 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 identifizierten Datenbank her und ändern Sie den Inhaber des Triggers in einen postgres-Nutzer.
Nicht übernommene 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 der vorbereiteten Anweisung aus.
Verworfene Flags Your installation contains deprecated flags for the new version . These flags must be removed before attempting an upgrade: (database: %s, Flag name: %s) Entfernen Sie das Datenbank-Flag aus der Instanzkonfiguration.

Datenbankinkompatibilitäten

In der folgenden Tabelle sind häufige Fehler im Zusammenhang mit Inkompatibilitäten von Datenformaten aufgeführt, die bei der Vorabprüfung des Upgrades 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 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 Ihren Datenbanktabellendefinitionen.
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 identifizierten Spalten so, dass sie einen benutzerdefinierten zusammengesetzten Typ oder einen Standarddatentyp verwenden. Zusammengesetzte Systemtypen sind möglicherweise nicht über 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. Möglicherweise müssen Sie Funktionssignaturen oder Logik anpassen, 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 mehrdeutigen Spaltenverweis 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 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 der vorherigen Hauptversion wiederherstellen

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 die Lesereplikate 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 Gesamtupgradedauer 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 das Upgrade einbeziehen, kann der Upgradevorgang je nach Anzahl der Replikate, die Ihre primäre Instanz hat, 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?
Ja, aber nur unter bestimmten Bedingungen. Sie können den Vorgang während der Hauptupgradephase abbrechen. Weitere Informationen zum Identifizieren des Zeitfensters, in dem ein Abbruch möglich ist, finden Sie unter Upgrade der Hauptversion abbrechen. Außerdem wird der Abbruch nicht unterstützt, wenn Sie Lesereplikate mit der primären Instanz einbeziehen. Wenn Sie die Möglichkeit zum Abbrechen beibehalten möchten, müssen Sie das Upgrade ohne Lesereplikate durchführen.
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, sofern das Flag nicht von Ihnen festgelegt wurde. Wenn Sie ein Flag konfiguriert haben, das in der Zielversion nicht unterstützt wird, müssen Sie das Flag vor dem Upgrade entfernen.

Nächste Schritte