PostgreSQL-Major-Upgrade (pg_upgrade / logische Replikation)

Upgrade auf eine neue Hauptversion (z. B. 16 → 17): Wahl der Methode (pg_upgrade --link / --copy / --clone oder nahezu unterbrechungsfreie Migration mit logischer Replikation), pg_upgrade --check, Kompatibilität der Extensions, Übernahme der Konfiguration, erneutes Sammeln der Statistiken, Neuaufbau der Standbys mit rsync oder pg_basebackup, Entfernen des alten Clusters und Rollback-Runbook. Einzelserver, Streaming Replication (Primary + Standbys) und Patroni-Cluster (offizielles Major-Upgrade-Verfahren von Patroni: Patroni wird gestoppt, pg_upgrade auf dem Leader, der DCS-Eintrag wird gelöscht, die Replicas werden von Patroni neu kopiert). RHEL-Familie und Debian/Ubuntu (inklusive pg_upgradecluster).

Für ein Update innerhalb derselben Hauptversion (z. B. 17.4 → 17.6) nutzt du statt dieses Guides pg-minor-update. Für dauerhafte Replikation auf Tabellenebene oder eine Teilmigration nimm pg-logical-repl, um eine kleine Datenbank per Dump auf einen anderen Server zu verschieben pg-dump-restore.

Topologie: In-place auf demselben Server (pg_upgrade; Einzelserver, Primary + Standbys oder Patroni-Cluster) oder auf einen neuen Server (logisch)

Szenarien

• Major-Upgrade — Upgrade auf eine neue Hauptversion (z. B. 16 → 17): Vorabprüfung, Backup, pg_upgrade oder logische Replikation, Verifizierung und Aufräumen.
• Rollback (Upgrade fehlgeschlagen / abgebrochen) — Das Upgrade ist mittendrin abgebrochen oder die neue Version macht Probleme: Rückkehr zur alten Version. Wurde bei --link der neue Cluster bereits gestartet, geht es nur noch über das Backup zurück.

Vor dem Start

• Der Quellcluster ist PostgreSQL … und aus dem PGDG-Repository installiert (pg-install). Die Zielversion … ist höher als die Quellversion.
• Anwendung und Treiber sind mit PostgreSQL … getestet; dasselbe Upgrade wurde vorher in einer Testumgebung geprobt. Die Abschnitte „Migration to Version“ in den Release Notes jeder Hauptversion bis … wurden gelesen (entfernte Parameter, Verhaltensänderungen).
• Für alle installierten Extensions gibt es eine Version für … (PostGIS, pg_repack, pgaudit, TimescaleDB…). Fehlt eine Extension für …, ist das Upgrade nicht möglich.
• …Für das neue Datenverzeichnis ist freier Platz in Höhe der aktuellen Datenmenge vorhanden.…Altes und neues Datenverzeichnis liegen im selben Dateisystem (Voraussetzung für Hardlinks); für WAL und den neuen Katalog sind einige GB frei.…Das Dateisystem unterstützt Reflink (XFS reflink=1 oder Btrfs) und beide Verzeichnisse liegen im selben Dateisystem.…
• Vorhandene Logical Replication Slots / Subscriptions wurden aufgelistet: …Bei einer Quelle ab PostgreSQL 17 übernimmt pg_upgrade die logischen Slots; alle Änderungen müssen aber konsumiert sein…Bei einer Quelle mit PostgreSQL … übernimmt pg_upgrade die logischen Slots nicht; sie müssen nach dem Upgrade neu angelegt werden….
• Vom Primary zu jedem Standby gibt es passwortloses SSH als Benutzer postgres, und auf den Standbys ist rsync installiert. Die Datenverzeichnisse folgen dem Schema …/<version>/data (rsync nutzt das gemeinsame übergeordnete Verzeichnis).
• Die Standbys sind im Streaming-Zustand; die pg_hba.conf des Primary erlaubt die Replikationsverbindung, und das Passwort von … steht auf den Standbys in ~postgres/.pgpass.
• Der Patroni-Cluster ist gesund: … ist der aktuelle Leader, alle Replicas sind streaming ohne Lag, kein Pending restart. Cluster-Name …, Konfiguration …, REST-API-Passwörter in /etc/patroni/patroni.env (Layout aus pg-patroni). Vom DCS (etcd) wurde ein Snapshot-Backup erstellt. Während des Upgrades ist der Cluster komplett down: Verbindungen über HAProxy/VIP werden abgewiesen.
• Die Patroni-Version unterstützt PostgreSQL … (Unterstützung der neuen Hauptversion laut Release Notes von Patroni). Ein älteres Patroni erkennt die Parameter und die Control-Datei der neuen Version unter Umständen nicht; aktualisiere Patroni bei Bedarf vorher per Rolling Upgrade.
• Auf dem Zielserver ist PostgreSQL … mit pg-install installiert, leer und in Betrieb; die …-Versionen der Extensions der Quelle sind installiert. Das Ziel erreicht Port … der Quelle.
• Die zu migrierenden Tabellen haben einen Primärschlüssel oder eine Replica Identity (sonst schlagen UPDATE/DELETE auf der Quelle fehl). Ergänze bei den aufgelisteten Tabellen einen PK oder setze ALTER TABLE … REPLICA IDENTITY FULL.
• Es gibt ein aktuelles Backup, dessen Restore getestet wurde… (pgBackRest)…; wenn möglich wird zusätzlich ein Server- oder Disk-Snapshot erstellt.… Bei der --link-Methode ist das nach dem Start des neuen Clusters der einzige Weg zurück.…

Phasen der Anleitung

• Vorabprüfung — Status des Patroni-Clusters prüfen · Eigenschaften des Clusters festhalten · Extension-RPMs/-debs auflisten · Prepared Transactions und lang laufende Transaktionen prüfen
• Vorbereitung des neuen Clusters — Neues Datenverzeichnis anlegen · Neuen Cluster mit denselben Eigenschaften anlegen (initdb) · Konfiguration in den neuen Cluster übernehmen · Auf Parameter prüfen, die in der neuen Version ungültig sind · Patroni-Parameter gegen die neue Version prüfen
• Backup und Rückfallpunkt — Backup erstellen (pgBackRest full) · Backup erstellen (pg_dumpall + Snapshot)
• Kompatibilitätsprüfung (pg_upgrade --check) — pg_upgrade --check
• Ausfallzeit: alten Cluster stoppen — Anwendungen stoppen · Letztes Backup zu Beginn der Ausfallzeit (pgBackRest incr) · Letztes logisches Backup zu Beginn der Ausfallzeit · Alten Primary stoppen · Patroni auf den Replicas stoppen · Patroni auf dem Leader stoppen …
• Upgrade — pg_upgrade ausführen · Upgrade mit pg_upgradecluster · conf.d-Dateien in den neuen Cluster übernehmen · pgBackRest-Konfiguration auf den neuen Cluster umstellen · bin_dir und data_dir in patroni.yml auf die neue Version umstellen · pgBackRest-Stanza auf die neue Version aktualisieren …
• Start des neuen Clusters — Neuen Cluster starten · Patroni auf dem Leader starten · Standbys sofort starten
• Arbeiten nach dem Upgrade — Extensions aktualisieren · Statistiken sammeln · pgBackRest-Prüfung und neues Vollbackup
• Verifizierung — Version, Parameter und Datenbanken · Patroni-Cluster verifizieren · Logs prüfen · Anwendungstests
• Entfernen des alten Clusters — Altes Datenverzeichnis löschen · Altes Datenverzeichnis auf den …Replicas…Standbys… löschen · Software der alten Version entfernen
• Vorbereitung des Quellservers — wal_level = logical · Quelle neu starten · Replikationsbenutzer anlegen · Ziel in pg_hba.conf eintragen · pg_hba neu laden · Publication anlegen
• Schema und Subscription auf dem Ziel — Passwörter der Quelle in .pgpass schreiben · Rollen (Globals) kopieren · Schema kopieren · Subscription anlegen · Auf das Ende der initialen Kopie warten · Lag prüfen
• Finale Umschaltung (Cutover) — Schreibzugriffe auf der Quelle stoppen · Prüfen, ob die letzten Änderungen übertragen wurden · Sequenzwerte übertragen · Subscription entfernen · Statistiken sammeln · Anwendungen auf das Ziel umstellen …
• Rollback — Neuen Cluster stoppen · Patroni auf den Replicas stoppen · Patroni auf dem Leader stoppen · pg_control zurückholen (--link, neuer Cluster nicht gestartet) · …Rollback aus dem Backup (--link, neuer Cluster gestartet)…Rollback aus dem logischen Backup (--link, neuer Cluster gestartet)… · Recovery ohne Patroni abschließen …