PostgreSQL 16 auf 18 per Tag: Was passiert und wie Sie zurückkommen
Ernstfall Teil 4: PostgreSQL 18.7 startet nicht auf Daten von 16.16, verliert aber nichts. Der Rückweg klappt sofort, Dump und pg_upgrade brauchten unter einer Minute. Das automatische Upgrade scheiterte im Test.
Mit KI erstellt – redaktionelle Prüfung ausstehend
Werbung Mit * markierte Links sind Werbelinks: Bei einem Kauf erhalten wir eine Provision, der Preis bleibt gleich. Als Amazon-Partner verdiene ich an qualifizierten Verkäufen. Mehr dazu

In der compose.yaml steht postgres:16, PostgreSQL 18 ist erschienen, also wird aus der 16 eine 18. Bei den meisten Diensten reicht das. Bei PostgreSQL nicht: Der Container startet nicht mehr, und die Anwendung dahinter steht. Für diese Anleitung wurde genau das mit einer Testdatenbank durchgespielt: erst der Fehler in drei Varianten, dann der Weg zurück, dann drei Wege nach vorn, jeder dreimal gemessen.
Dies ist Teil 4 der Reihe „Ernstfall“. Jeder Teil macht absichtlich etwas kaputt, misst, was passiert, und zeigt den Weg zurück.
Was Sie brauchen
- Einen Linux-Server mit Docker und Docker Compose, siehe Docker und Docker Compose auf Linux installieren.
- PostgreSQL im Container mit dem Datenordner als Bind-Mount. Die Beispiele nutzen den Dienst
db, den Ordner./dund den bisher üblichen Mount auf/var/lib/postgresql/data. - Freien Platz für eine Kopie des Datenordners und für den neuen Ordner oder den Dump. Im Test lagen Sicherung, alter und neuer Ordner gleichzeitig vor.
- Eine Wartungspause. Während des Upgrades ist die Datenbank nicht erreichbar.
Schritt 1: Zurück auf die alte Version
Steht die Datenbank nach dem Tag-Wechsel, dann stellen Sie zuerst den alten Zustand wieder her. Tragen Sie in der compose.yaml wieder die alte Version ein, am besten mit voller Versionsnummer statt nur 16, und nehmen Sie alle Änderungen am Mount zurück:
services:
db:
image: postgres:16.16
environment:
POSTGRES_PASSWORD: ${DBPW}
volumes:
- ./d:/var/lib/postgresql/data
- ./dump:/dump$ docker compose up -d dbIm Test hatte der Datenordner vorher alle drei Fehlversuche aus dem Abschnitt „Was beim Tag-Wechsel passiert“ hinter sich. PostgreSQL 16.16 startete trotzdem beim ersten Versuch.
Verifizieren: Die Datenbank antwortet mit der alten Version, und Ihre Daten sind da:
$ docker compose exec -T db psql -U postgres -Atc "SHOW server_version"16.16 (Debian 16.16-1.pgdg13+1)Schritt 2: Datenordner sichern
Vor jedem Weg nach vorn steht eine Kopie des Datenordners bei gestoppter Datenbank. Warum eine Kopie im laufenden Betrieb nicht reicht, zeigt Teil 1 der Reihe mit 348 geprüften Kopien.
$ docker compose stop db
$ sudo cp -a d d-sicherung-16Verifizieren: sudo du -sm d d-sicherung-16 zeigt für beide Ordner dieselbe Größe, im Test 2.376 MB.
Schritt 3, Weg A: Dump aus 16, einspielen in 18
Der einfachste Weg kommt ohne Zusatzwerkzeug aus. Die alte Datenbank schreibt alles in eine SQL-Datei, eine frische Datenbank der neuen Version liest sie ein. Starten Sie dafür noch einmal die alte Version und ziehen Sie den Dump. Der Ordner ./dump ist wie in Schritt 1 im Container als /dump eingebunden:
$ docker compose up -d db
$ docker compose exec -T db sh -c 'pg_dumpall -U postgres > /dump/alles.sql'
$ docker compose stop dbDanach stellen Sie den Dienst auf die neue Version und einen neuen, leeren Ordner um. Ab PostgreSQL 18 gehört der Mount auf /var/lib/postgresql, nicht mehr auf den Unterordner data:
services:
db:
image: postgres:18.7
environment:
POSTGRES_PASSWORD: ${DBPW}
volumes:
- ./d18:/var/lib/postgresql
- ./dump:/dump$ docker compose up -d db
$ docker compose exec -T db sh -c 'psql -U postgres -q -f /dump/alles.sql postgres'
$ docker compose exec -T db vacuumdb -U postgres --all --analyze-in-stagesBeim Einspielen erschien im Test genau eine Fehlermeldung: ERROR: role "postgres" already exists. Sie ist harmlos, weil die neue Datenbank diese Rolle schon mitbringt. Die Rolle der Anwendung kam mit dem Dump mit.
Verifizieren: SHOW server_version meldet 18.7, die Datenbanken sind vorhanden, und pg_amcheck endet ohne Ausgabe:
$ docker compose exec -T db pg_amcheck -U postgres -d bank --install-missing --heapallindexedSchritt 3, Weg B: pg_upgrade mit beiden Versionen
pg_upgrade baut den Datenordner direkt um und braucht dafür die Programme beider Versionen. Das offizielle Image enthält nur eine. Das Image tianon/postgres-upgrade vom Betreuer des offiziellen Images bringt beide mit. Der alte Ordner wird unter dem Pfad der alten Version eingebunden, ein leerer Ordner unter dem der neuen:
services:
upgrade:
image: tianon/postgres-upgrade:16-to-18
environment:
POSTGRES_INITDB_ARGS: --no-data-checksums
volumes:
- ./d:/var/lib/postgresql/16/data
- ./d18:/var/lib/postgresql/18/docker$ docker compose -f upgrade.yaml run --rm upgradeDie Zeile mit --no-data-checksums ist die erste Falle. PostgreSQL 18 legt neue Datenbanken mit Prüfsummen an, ältere Versionen taten das nicht. Ohne die Zeile brach pg_upgrade im Test nach 6 bis 13 Sekunden ab:
old cluster does not use data checksums but the new one does
Failure, exitingDie zweite Falle zeigt sich erst danach. pg_upgrade übernimmt die Daten, aber nicht die Datei pg_hba.conf. Der neue Ordner enthält die Vorgabe, die nur Verbindungen aus dem Container selbst erlaubt. Die Datenbank startete im Test, Abfragen im Container liefen, aber eine Verbindung aus dem Nachbarcontainer wurde abgewiesen:
FATAL: no pg_hba.conf entry for host "172.21.0.3", user "postgres", database "bank", no encryptionKopieren Sie deshalb die alte Datei in den neuen Ordner und binden Sie ihn unter dem Pfad ein, an dem das Image ab Version 18 seine Daten ablegt. Im Test genügte nach dem Kopieren ein Neustart, danach klappte die Anmeldung von außen, auch mit der Rolle der Anwendung:
$ sudo cp d/pg_hba.conf d18/pg_hba.confservices:
db:
image: postgres:18.7
environment:
POSTGRES_PASSWORD: ${DBPW}
volumes:
- ./d18:/var/lib/postgresql/18/docker$ docker compose up -d db
$ docker compose exec -T db vacuumdb -U postgres --all --analyze-in-stagesDer Befehl vacuumdb baut die Statistiken neu auf, die pg_upgrade nicht vollständig überträgt. Mit dem Zusatz --link und einem gemeinsamen Mount auf /var/lib/postgresql verknüpft pg_upgrade die Dateien, statt sie zu kopieren. Auch das lief im Test dreimal fehlerfrei. Nach dem ersten Start der neuen Version ist der alte Ordner laut PostgreSQL-Dokumentation dann aber nicht mehr verwendbar, die Sicherung aus Schritt 2 ist in diesem Fall der einzige Weg zurück.
Verifizieren: pg_upgrade endet mit Upgrade Complete. Danach meldet SHOW server_version 18.7, pg_amcheck endet ohne Ausgabe, und die Anwendung kann sich verbinden.
So wurde gemessen
Getestet mit PostgreSQL 16.16 und 18.7 aus den offiziellen Images, tianon/postgres-upgrade:16-to-18 und pgautoupgrade/pgautoupgrade:18-trixie, unter Docker 29.8.2 mit Docker Compose 5.5.1. Die Testdatenbank enthielt fünf Millionen Konten und 300.000 Buchungen mit einem zusätzlichen Index, dazu eine eigene Rolle für die Anwendung. Der Datenordner war 2.376 MB groß. Als Kontrolle dienten die Summe aller Kontostände, die Zahl der Buchungen und pg_amcheck.
Der Datenordner wurde einmal bei gestoppter Datenbank gesichert. Jeder Weg startete von einer frischen Kopie dieser Sicherung und lief dreimal. Die Zeiten sind Mediane aus drei Läufen auf einem lokalen Datenträger, die Gesamtdauer ist die Summe der Schritte. Auf langsameren Platten dauert alles entsprechend länger.
Ergebnis 1: Was beim Tag-Wechsel passiert

Alle drei naheliegenden Varianten endeten gleich: Der Container beendete sich mit Fehler, die Datenbank blieb aus.
| Variante | Ergebnis | Meldung |
|---|---|---|
| Nur den Tag auf 18.7 geändert | startet nicht | Error: in 18+, these Docker images are configured to store database data in a format which is compatible with "pg_ctlcluster" |
Tag 18.7 und PGDATA auf den alten Pfad gesetzt | startet nicht | FATAL: database files are incompatible with server |
Tag 18.7 und Mount auf /var/lib/postgresql umgestellt | startet nicht | dieselbe Meldung wie in der ersten Zeile, mit dem Pfad /var/lib/postgresql |
Die gute Nachricht steckt im Verhalten des Images. Es erkennt die alten Daten und weigert sich zu starten, statt daneben eine leere Datenbank anzulegen. Im Test enthielt der Datenordner danach dieselben Dateien wie vorher, in der dritten Variante kam nur ein Unterordner 18/docker ohne Daten hinzu. Der Rückweg aus Schritt 1 startete danach sofort, mit der vollen Summe, allen 300.000 Buchungen und ohne Befund von pg_amcheck.
Ergebnis 2: Zwei Wege nach vorn, beide unter einer Minute

| Weg | Schritte | Dauer gesamt | Prüfsummen danach |
|---|---|---|---|
A: pg_dumpall und einspielen | Dump 3,4 s, einspielen 20,5 s, Statistik 7,4 s | 31,2 s | ein |
B: pg_upgrade, Kopie | Upgrade 6,9 s, Statistik 7,3 s | 14,2 s | aus |
B: pg_upgrade --link | Upgrade 8,4 s | 8,4 s ohne Statistik | aus |
Alle neun Läufe endeten mit vollständigen Daten: Summe und Zahl der Buchungen stimmten, pg_amcheck fand nichts. Bei Weg A und bei pg_upgrade mit Kopie wurde zusätzlich geprüft, dass die Rolle der Anwendung vorhanden ist. Bei dieser Größe ist die Dauer kein Argument für oder gegen einen Weg. Der Dump war 997 MB groß.
Der Unterschied liegt im Ergebnis. Nach Weg A ist die Datenbank neu aufgebaut und hat Prüfsummen, weil PostgreSQL 18 sie für neue Datenbanken einschaltet. Nach Weg B bleibt sie ohne Prüfsummen, wie sie unter Version 16 angelegt wurde. Dafür braucht Weg B keine SQL-Datei.
Ergebnis 3: Das automatische Upgrade scheiterte
Das Image pgautoupgrade/pgautoupgrade ist für den bequemsten Weg gedacht: Image-Namen tauschen, starten, der Container erledigt das Upgrade selbst. Im Test brach der Container in allen acht Versuchen an derselben Stelle ab. Die Ursache stand im Protokoll von pg_upgrade, ausgelesen in einem der Läufe:
pg_restore: error: could not execute query: ERROR: unrecognized parameter "pg_attver"Das Image enthielt zum Testzeitpunkt PostgreSQL 18.6 und war laut Registry eine Woche älter als das Image mit 16.16. Vermutlich liegt hier die Ursache: Das Werkzeug kannte eine Angabe noch nicht, die der neuere Stand der alten Version mitliefert. Geprüft wurde diese Erklärung nicht.
Wichtiger als die Ursache ist der Zustand danach. Der Datenordner war umgebaut: Die alten Dateien lagen in einem Unterordner old, daneben ein halb fertiger Ordner new und eine Sperrdatei. PostgreSQL 16.16 startete auf diesem Ordner nicht, 18.7 mit PGDATA auf dem alten Pfad ebenfalls nicht, und ein zweiter Start des Upgrade-Images brach mit Upgrade lock file already exists ab. Zurück ging es von Hand, bei gestopptem Container:
$ sudo sh -c 'cd d && rm -rf new upgrade_in_progress.lock && mv old/* . && rmdir old'Danach startete PostgreSQL 16.16 wieder, mit allen Daten und ohne Befund. Wer vorher die Kopie aus Schritt 2 gezogen hat, spielt stattdessen einfach diese zurück.
Was das für Ihren Server heißt
Schreiben Sie bei Datenbanken die Hauptversion fest in die compose.yaml, besser die volle Versionsnummer. Ein Tag wie postgres:latest führt beim nächsten großen Sprung genau in diesen Stillstand. Nehmen Sie PostgreSQL aus automatischen Updates heraus oder beschränken Sie diese auf Unterversionen. Wie das mit den gängigen Werkzeugen geht, zeigt Docker-Container automatisch aktualisieren.
Ein Upgrade-Werkzeug sollte mindestens so aktuell sein wie die Datenbank, die es umbauen soll. Prüfen Sie vor dem Upgrade, welche Version im Image steckt, und testen Sie den Lauf an einer Kopie des Datenordners. Mit der Kopie aus Schritt 2 kostet ein gescheiterter Versuch nur Zeit.
Typische Fehler
Error: in 18+, these Docker images are configured to store database data in a format which is compatible with "pg_ctlcluster"Das Image 18 hat alte Daten im Mount gefunden. Stellen Sie den Tag zurück wie in Schritt 1 und gehen Sie dann Weg A oder B.
FATAL: database files are incompatible with serverIm Detail steht, dass der Ordner von Version 16 stammt. PostgreSQL liest Datenordner einer anderen Hauptversion nicht. Auch hier hilft nur Schritt 1.
old cluster does not use data checksums but the new one doesSetzen Sie für
pg_upgradedie VariablePOSTGRES_INITDB_ARGSauf--no-data-checksumsund leeren Sie den neuen Ordner vor dem nächsten Versuch.no pg_hba.conf entry for hostnach dem UpgradeDer neue Ordner enthält die Vorgabe statt Ihrer Zugriffsregeln. Kopieren Sie die alte
pg_hba.confin den neuen Ordner und starten Sie die Datenbank neu.initdb: error: directory "/var/lib/postgresql/data" exists but is not emptySo meldete sich PostgreSQL 16.16 auf dem Ordner, den das gescheiterte automatische Upgrade hinterlassen hatte. Räumen Sie ihn auf wie in Ergebnis 3 oder spielen Sie die Sicherung zurück.
Häufige Fragen
Gilt das auch für den Sprung von 17 auf 18?
Die Regel, dass PostgreSQL keinen Datenordner einer anderen Hauptversion liest, gilt für jeden Sprung über eine Hauptversion. Für 17 gibt es das Upgrade-Image mit dem Tag 17-to-18.
Kann ich die Prüfsummen nach pg_upgrade nachträglich einschalten?
Ja, PostgreSQL bringt dafür das Werkzeug pg_checksums mit, das bei gestoppter Datenbank läuft.
Betrifft das auch Unterversionen wie 16.15 auf 16.16?
Nein. Innerhalb einer Hauptversion bleibt das Format des Datenordners gleich, hier genügt der neue Tag.
Fazit
Der Versionssprung per Tag endet bei PostgreSQL im Stillstand, aber nicht im Datenverlust: Das Image verweigert den Start, und die alte Version läuft danach wieder, als wäre nichts gewesen. Der Weg nach vorn ist mit Dump oder pg_upgrade eine Sache von Minuten, wenn man die beiden Fallen mit den Prüfsummen und der pg_hba.conf kennt. Riskant wurde es im Test erst dort, wo ein Werkzeug den Datenordner selbstständig umbaute. Im nächsten Teil der Reihe fluten Container-Logs die Platte.
Weiterführende Anleitungen und Quellen
- Ernstfall Teil 11: Zertifikat abgelaufen, Uhr falsch
- Ernstfall Teil 12: SQLite auf der Netzfreigabe
- Ernstfall Teil 13: Harter Abbruch
- Ernstfall Teil 1: Datenbank im laufenden Betrieb kopiert
- Ernstfall Teil 2: Platte voll
- Ernstfall Teil 3: Update zurückdrehen
- Ernstfall Teil 5: Container-Logs fluten die Platte
- Ernstfall Teil 6: down -v, prune, rm
- Ernstfall Teil 7: Angreifer kennt das Backup-Passwort
- Ernstfall Teil 8: Restore-Rennen
- Ernstfall Teil 9: Registry weg, Internet weg
- Ernstfall Teil 10: Admin-Passwort weg
- PostgreSQL pg_dump und pg_restore
- Docker-Container automatisch aktualisieren
- Docker Compose absichern
- PostgreSQL: pg_upgrade
- PostgreSQL: Upgrading a PostgreSQL Cluster
- docker-library/postgres: neuer Datenpfad ab Version 18
- tianon/docker-postgres-upgrade
- pgautoupgrade/docker-pgautoupgrade


