PostgreSQL auf eine neue Hauptversion bringen

Kleine Updates von PostgreSQL (etwa 17.5 auf 17.6) sind harmlos: Paket aktualisieren, Dienst neu starten. Eine neue Hauptversion (15 auf 17) ist anders: Das Format der Daten auf der Platte ändert sich, und die neue Version kann die Dateien der alten nicht einfach öffnen. Die Daten müssen umgezogen werden. Debian nimmt dir dabei viel ab, aber nicht die Entscheidung, wann und wie.

Warum das oft vergessen wird#

Beim Upgrade von Debian 12 auf 13 installiert Debian die neue PostgreSQL-Version neben der alten. Die Datenbank läuft weiter, wie vorher, auf der alten Version. Das ist Absicht: Niemand soll beim Betriebssystem-Upgrade ungefragt seine Datenbank umbauen. Die Folge ist aber, dass viele Server jahrelang eine Version betreiben, für die es irgendwann keine Updates mehr gibt.

pg_lsclusters

Ver Cluster Port Status Owner    Data directory
15  main    5432 online postgres /var/lib/postgresql/15/main
17  main    5433 online postgres /var/lib/postgresql/17/main

So sieht es typischerweise nach dem Distributions-Upgrade aus: Die alte Version läuft auf 5432 mit deinen Daten, die neue auf 5433 leer.

Vorher#

Sicherung, und zwar logisch mit pg_dump bzw. pg_dumpall. Sie ist unabhängig von der Version und lässt sich in jede neuere einspielen. Wie das geht, steht in Datenbank sichern und wirklich zurückspielen.
Erweiterungen prüfen. Nutzt deine Datenbank Erweiterungen (PostGIS, pgvector, TimescaleDB), müssen die auch für die neue Version installiert sein.

sudo -u postgres psql -c "SELECT extname, extversion FROM pg_extension;" -d deine_db
apt list --installed 2>/dev/null | grep postgresql-15-      # Pakete, die es für 17 auch braucht

Release Notes lesen, für jede übersprungene Hauptversion den Abschnitt „Migration“. Dort stehen Änderungen, die Anwendungen treffen können.

Der Weg unter Debian: pg_upgradecluster#

Zuerst den leeren neuen Cluster entfernen, den Debian angelegt hat. Er würde sonst den Namen und Port blockieren:

pg_dropcluster 17 main --stop

Dann umziehen:

pg_upgradecluster 15 main

Standardmäßig arbeitet pg_upgradecluster mit einem Dump und Wiedereinspielen. Das ist der langsame, aber robuste Weg: Die alte Datenbank bleibt vollständig erhalten, und du kannst jederzeit zurück. Am Ende läuft der neue Cluster auf dem alten Port (5432), der alte ist angehalten und auf einen anderen Port verschoben.

Die Datenbank ist während des Umzugs nicht beschreibbar. Wie lange das dauert, hängt von der Größe ab. Bei großen Datenbanken lohnt einer der schnelleren Modi.

Schneller: upgrade und link#

pg_upgradecluster -m upgrade 15 main          # nutzt pg_upgrade, kopiert Dateien
pg_upgradecluster -m link 15 main             # nutzt pg_upgrade mit harten Links

Modus	Geschwindigkeit	Rückweg
`dump` (Standard)	langsam, proportional zur Datenmenge	alter Cluster bleibt unberührt
`upgrade`	schneller, kopiert Dateien	alter Cluster bleibt unberührt, braucht doppelten Platz
`link`	sehr schnell, fast unabhängig von der Größe	kein Rückweg, sobald der neue Cluster gestartet wurde

Der Haken am Link-Modus

Mit -m link teilen sich alter und neuer Cluster dieselben Dateien. Sobald der neue Cluster läuft und schreibt, ist der alte nicht mehr sicher benutzbar. Der Rückweg führt dann nur noch über eine Sicherung. Link-Modus also nur mit frischer, geprüfter Sicherung.

Danach#

pg_lsclusters                                   # 17 online auf 5432, 15 down
sudo -u postgres psql -c "SELECT version();"

Statistiken, die der Planer für schnelle Abfragen braucht, werden bei pg_upgrade nicht vollständig übernommen. Ohne sie sind Abfragen in den ersten Stunden spürbar langsamer:

sudo -u postgres vacuumdb --all --analyze-in-stages

Dann die Anwendung testen. Läuft alles ein paar Tage stabil, den alten Cluster entfernen:

pg_dropcluster 15 main
apt purge postgresql-15 postgresql-client-15

Die Einstellungen aus der alten postgresql.conf übernimmt pg_upgradecluster. Prüfe trotzdem die fünf Einstellungen aus PostgreSQL auf dem VPS, weil sich Standardwerte zwischen Versionen ändern können.

Mit Docker#

Im Container gibt es kein pg_upgradecluster. Der einfachste Weg ist der logische:

docker compose exec db pg_dumpall -U postgres > alles.sql
docker compose down
# Image-Tag in compose.yaml von postgres:15 auf postgres:17 ändern,
# Datenverzeichnis beiseitelegen (nicht löschen), neues leeres Verzeichnis angeben
docker compose up -d db
docker compose exec -T db psql -U postgres < alles.sql

Nur den Image-Tag zu ändern und neu zu starten, funktioniert nicht: PostgreSQL 17 verweigert den Start mit einem Datenverzeichnis von 15. Das ist eine Schutzfunktion, kein Fehler. Es gibt Images aus der Community, die pg_upgrade automatisch ausführen; sie sparen Zeit bei großen Datenbanken, und die Sicherung vorher brauchst du trotzdem.

Häufige Fragen#

Kann ich Versionen überspringen, etwa 13 auf 17?#

Ja, pg_upgrade und der Dump-Weg können mehrere Hauptversionen auf einmal überspringen. Lies dann die Migrationshinweise aller übersprungenen Versionen.

Wie lange wird eine Hauptversion gepflegt?#

Das PostgreSQL-Projekt pflegt jede Hauptversion fünf Jahre. Das Ende steht auf postgresql.org unter „Versioning Policy“. Debian liefert für die Version seiner Distribution Updates, solange die Distribution unterstützt wird.

Brauche ich eine neuere Version, als Debian mitbringt?#

Dann gibt es das offizielle Paketarchiv des PostgreSQL-Projekts (apt.postgresql.org). Dieselben Werkzeuge (pg_upgradecluster) funktionieren damit genauso.

Was, wenn die Anwendung mit der neuen Version nicht klarkommt?#

Beim Dump- und Upgrade-Modus: den neuen Cluster anhalten, den alten wieder auf 5432 legen und starten. Genau dafür lässt du den alten Cluster ein paar Tage stehen.

Kurz gesagt#

Eine neue Hauptversion braucht einen Datenumzug, kein einfaches Update.
Nach einem Distributions-Upgrade läuft die alte Version weiter; pg_lsclusters zeigt es.
pg_dropcluster 17 main --stop, dann pg_upgradecluster 15 main.
Link-Modus ist schnell, aber ohne Rückweg; nur mit geprüfter Sicherung.
Danach vacuumdb --all --analyze-in-stages, den alten Cluster erst nach ein paar Tagen löschen.