By Ralf-Peter Kleinert
PostgreSQL-Datenbankupgrade von Version 17 auf Version 18. In diesem Artikel zeige ich Ihnen Schritt für Schritt, wie Sie die PostgreSQL-Datenbank Ihrer Paperless-ngx-Installation von PostgreSQL 17 auf PostgreSQL 18 aktualisieren. Die Anleitung basiert auf meiner eigenen Installationsmethode sowie den dazugehörigen YouTube-Videos und wurde in einer realen Umgebung getestet.
Achtung: Ein Major-Upgrade von PostgreSQL ist nicht mit einem normalen Image-Update erledigt. Wer einfach den Docker-Tag auf PostgreSQL 18 ändert, riskiert, dass die Datenbank nicht mehr startet.
Wichtiger Hinweis: Es gibt zahlreiche Möglichkeiten, Paperless-ngx zu installieren. Je nach Installationsart können sich Verzeichnisse, Dateinamen, Docker-Konfigurationen oder sogar das verwendete Datenbanksystem (z. B. PostgreSQL, MariaDB oder SQLite) unterscheiden. Diese Anleitung bezieht sich ausschließlich auf die von mir verwendete Paperless Docker-Installation. Für andere Installationsvarianten müssen die einzelnen Schritte gegebenenfalls angepasst werden. Unabhängig davon empfiehlt auch die offizielle Paperless-ngx-Dokumentation, vor einem Datenbank-Upgrade stets ein vollständiges Backup anzulegen und die Upgrade-Hinweise des jeweiligen Datenbanksystems zu beachten.
Voraussetzungen zum DB Upgrade Postgre 17 auf 18
Diese Anleitung setzt folgende Umgebung voraus:
- PostgreSQL 17 als Datenbankserver
- Debian-Linux-VM (in meinem Fall unter Proxmox VE)
- Docker und Docker Compose
- Paperless-ngx 2.20.15
- Installation im Verzeichnis /opt/paperless
- Konfiguration über eine docker-compose.yml
Meine Anleitung wurde mehrfach erfolgreich getestet. Deshalb beschränke ich mich bewusst auf die einfachsten und wichtigsten Prüfungen, die sich in der Praxis bewährt haben. Natürlich wäre es theoretisch möglich, die PostgreSQL-17-Datenbank bis ins kleinste Detail zu analysieren und anschließend mit der PostgreSQL-18-Datenbank zu vergleichen. Für diese Anleitung war es mir jedoch wichtig, den Upgrade-Prozess so einfach und nachvollziehbar wie möglich zu halten, damit er auch für weniger erfahrene Anwender gut umsetzbar bleibt.
Wichtig
Bitte schreiben Sie unter den Artikel einen Kommentar ob alles funktionert hat! Ich kann sonst keine Korrekturen anbieten.
Schritt 1 – VM-Vollbackup erstellen
Bevor Sie Änderungen an der Datenbank oder der Docker-Konfiguration vornehmen, sollten Sie unbedingt ein vollständiges Backup der virtuellen Maschine erstellen. Falls während des Upgrades etwas schiefgeht, können Sie den ursprünglichen Zustand der gesamten Installation innerhalb weniger Minuten wiederherstellen. Dieser Schritt ist Ihre wichtigste Absicherung und sollte niemals übersprungen werden.
Schritt 2 – SSH-Verbindung zur Paperless-VM herstellen
Melden Sie sich nun per SSH an Ihrer Paperless-VM an. Alle weiteren Arbeiten, wie das Erstellen des Datenbank-Backups und das Anpassen der Docker-Konfiguration, werden direkt auf der Linux-Konsole durchgeführt.
Schritt 3 – Backup-Ordner für die Datenbank erstellen
Bevor das Datenbank-Backup erstellt wird, legen wir einen eigenen Ordner dafür an. So bleiben Sicherungen sauber von der eigentlichen Installation getrennt und können bei Bedarf später leicht wiedergefunden oder auf ein anderes System kopiert werden.
mkdir -p /opt/paperless/backups
Schritt 4 – Datenbank-Dump erstellen
In diesem Schritt erstellen wir eine vollständige Sicherung der PostgreSQL-Datenbank. Dieses Backup dient als zusätzliche Absicherung und ermöglicht es, die Datenbank bei Bedarf jederzeit wiederherzustellen – unabhängig vom VM-Backup.
cd /opt/paperless
docker compose -f /opt/paperless/docker-compose.yml exec -T db \
pg_dump -U paperless -Fc paperless \
> /opt/paperless/backups/paperless_pg17.dump
Schritt 5 – Datenbank-Dump prüfen
Nach dem Erstellen des Datenbank-Dumps sollten Sie überprüfen, ob die Sicherungsdatei fehlerfrei erstellt wurde. So stellen Sie sicher, dass das Backup im Ernstfall auch tatsächlich für eine Wiederherstellung verwendet werden kann.
cd /opt/paperless
Mit diesem Befehl lesen Sie die Sicherungsdatei aus und zeigen die ersten 20 Einträge des Datenbank-Dumps an. Kann pg_restore den Inhalt fehlerfrei auflisten, ist das ein gutes Zeichen dafür, dass die Backup-Datei korrekt erstellt wurde und verwendet werden kann:
docker compose -f /opt/paperless/docker-compose.yml exec -T db \
pg_restore -l \
< /opt/paperless/backups/paperless_pg17.dump \
| head -n 20
Schritt 6 – docker-compose.yml sichern
Bevor Änderungen an der Docker-Konfiguration vorgenommen werden, sollten Sie die aktuelle docker-compose.yml sichern. Falls später ein Problem auftritt oder Sie das Upgrade rückgängig machen möchten, können Sie jederzeit auf die ursprüngliche Konfiguration zurückgreifen.
Mit diesem Befehl wird im Verzeichnis /opt/paperless eine Sicherheitskopie der Datei docker-compose.yml unter dem Namen docker-compose.yml.pg17 erstellt. So bleibt die ursprüngliche Konfiguration erhalten und kann bei Bedarf jederzeit wiederhergestellt werden:
cp /opt/paperless/docker-compose.yml \
/opt/paperless/docker-compose.yml.pg17
Schritt 7 – Paperless-ngx stoppen
Bevor die Datenbank aktualisiert wird, müssen die Paperless-ngx-Container gestoppt werden. Die PostgreSQL-Datenbank darf dabei jedoch nicht beendet werden, da in den folgenden Schritten noch weitere Datenbankbefehle und Sicherungen ausgeführt werden. Verwenden Sie daher nicht docker compose down, sondern stoppen Sie ausschließlich die benötigten Paperless-Container. So bleibt der Datenbankserver weiterhin erreichbar.
cd /opt/paperless
docker compose stop paperless
Schritt 8 – Finalen Datenbank-Dump erstellen
Nachdem alle Paperless-Container gestoppt wurden, erstellen wir einen letzten Datenbank-Dump. Sie werden bei der anschließenden Prüfung feststellen, dass sich die Größe der Sicherungsdatei gegenüber dem ersten Dump geringfügig verändert hat. Das liegt daran, dass während des laufenden Betriebs noch Datenbankeinträge geändert werden können. Mit diesem finalen Dump stellen Sie sicher, dass Sie eine konsistente und möglichst aktuelle Sicherung für das Upgrade verwenden.
cd /opt/paperless
Mit diesem Befehl wird der finale Datenbank-Dump im Verzeichnis /opt/paperless/backups unter dem Namen paperless_pg17_final.dump erstellt. Diese Sicherungsdatei dient als Grundlage für das spätere Wiederherstellen der Daten in PostgreSQL 18:
docker compose exec -T db \
pg_dump -U paperless -Fc paperless \
> /opt/paperless/backups/paperless_pg17_final.dump
Prüfen der Dump-Größen. Notieren Sie sich die Größen-, Zahlen-Werte der .dump-Datein, denn diese benötigen wir später noch mal.
cd /opt/paperless
ls -la
Schritt 9 – Finalen Datenbank-Dump prüfen
Prüfen Sie auch den finalen Datenbank-Dump, bevor Sie mit dem eigentlichen Upgrade beginnen. So stellen Sie sicher, dass die aktuelle Sicherungsdatei fehlerfrei erstellt wurde und im Bedarfsfall für eine Wiederherstellung verwendet werden kann. Dieser kurze Kontrollschritt kann später viel Zeit und Ärger ersparen.
docker compose exec -T db pg_restore -l \
< /opt/paperless/backups/paperless_pg17_final.dump \
| head -n 20
Wenn auch bei dieser Prüfung keine Fehlermeldungen in der Shell ausgegeben werden, können Sie davon ausgehen, dass der finale Datenbank-Dump erfolgreich erstellt wurde und für das Upgrade auf PostgreSQL 18 verwendet werden kann.
Schritt 10 – Datenbank stoppen
Nachdem der finale Datenbank-Dump erfolgreich erstellt und überprüft wurde, kann die PostgreSQL-17-Datenbank gestoppt werden. Da nun keine weiteren Sicherungen mehr benötigt werden, kann der Datenbankserver sicher heruntergefahren und für das Upgrade vorbereitet werden.
cd /opt/paperless
docker compose stop db
Schritt 11 docker-compose.yml öffnen
Da wir die ursprüngliche docker-compose.yml bereits gesichert haben, können wir sie nun gefahrlos bearbeiten. In den folgenden Schritten werden lediglich die PostgreSQL-Version sowie die dazugehörigen Abhängigkeiten angepasst. Alle anderen Einstellungen bleiben unverändert.
cd /opt/paperless
nano docker-compose.yml
Schritt 12 – docker-compose.yml anpassen
Nun wird die Datei docker-compose.yml für PostgreSQL 18 vorbereitet. Dazu wird das Docker-Image auf PostgreSQL 18 umgestellt und gleichzeitig ein neues Daten-Volume angelegt. Das bisherige Volume db_data der PostgreSQL-17-Installation bleibt dadurch vollständig erhalten. So können Sie bei Problemen jederzeit auf die alte Datenbank zurückgreifen, ohne dass deren Daten überschrieben werden.
Ändern Sie den Eintrag
image: postgres:17
in
image: postgres:18
Ändern Sie den Volume-Eintrag
db_data:/var/lib/postgresql/data
in
db_data_18:/var/lib/postgresql
Fügen Sie anschließend im Abschnitt volumes: zusätzlich das neue Volume
db_data_18:
hinzu.
Schritt 13 – docker-compose.yml prüfen
Bevor die Container wieder gestartet werden, sollten Sie die geänderte docker-compose.yml auf Syntaxfehler überprüfen. Der folgende Befehl liest die Konfiguration ein und meldet eventuelle Fehler. Werden keine Fehlermeldungen ausgegeben, können Sie mit dem nächsten Schritt fortfahren.
Da auf der rechten Seite oben ist ein Kaffeekasse-Button. Wenn das Upgrade und die Datenbank-Migration funktioniert hat – vielleicht ist ja n Kaffe für mich drin?
cd /opt/paperless
docker compose config
Schritt 14 – Composing der Datenbank starten
Mit diesem Befehl wird zunächst das PostgreSQL-18-Image heruntergeladen, sofern es sich noch nicht auf dem System befindet. Anschließend erstellt Docker den neuen Datenbank-Container und initialisiert die neue, leere PostgreSQL-18-Datenbank im zuvor angelegten Volume. Damit ist die Datenbank für die Wiederherstellung des Backups vorbereitet.
cd /opt/paperless
docker compose up -d db
Schritt 15 – Finalen Datenbank-Dump importieren
Da wir zuvor einen vollständigen und geprüften Datenbank-Dump erstellt haben, können wir diesen nun in die neue PostgreSQL-18-Datenbank importieren. Dadurch werden sämtliche Daten, Dokumenteinstellungen und Informationen aus der bisherigen PostgreSQL-17-Datenbank in die neue Datenbank übernommen.
cd /opt/paperless
docker compose exec -T db \
pg_restore \
-U paperless \
-d paperless \
--no-owner \
--exit-on-error \
< /opt/paperless/backups/paperless_pg17_final.dump
Schritt 16 – Größe der Dump-Datei prüfen
Nach dem Import sollten Sie die Größe der finalen Dump-Datei noch einmal mit den zuvor notierten Werten vergleichen. Eventuell müssen die Werte umgerechnet werden. Nutzen sie dazu Goolge. Stimmen die Größen ungefähr überein, ist das ein weiterer Hinweis darauf, dass der Datenbank-Import erfolgreich durchgeführt wurde. Geringfügige Abweichungen sind dabei in der Regel unkritisch.
cd /opt/paperless
docker compose exec db \
psql -U paperless -d paperless \
-c "SELECT pg_size_pretty(pg_database_size('paperless'));"
Schritt 17 – Tabellenanzahl prüfen
Wenn eine größere Anzahl an Tabellen vorhanden ist, ist das ein gutes Zeichen dafür, dass die PostgreSQL-18-Datenbank erfolgreich initialisiert wurde und der Import der Daten durchgeführt werden konnte.
cd /opt/paperless
docker compose exec db \
psql -U paperless -d paperless \
-c "SELECT count(*) FROM information_schema.tables WHERE table_schema='public';"
Schritt 18 – Paperless starten
Nachdem die neue PostgreSQL-18-Datenbank erfolgreich eingerichtet und überprüft wurde, kann Paperless wieder gestartet werden. Die Anwendung verbindet sich nun mit der neuen Datenbank und sollte wie gewohnt zur Verfügung stehen.
cd /opt/paperless
docker compose up -d
Schritt 19 – Paperless im Browser öffnen
Geben Sie Paperless nach dem Start etwa zwei bis fünf Minuten Zeit, damit alle Dienste vollständig hochfahren können. Anschließend können Sie die Weboberfläche im Browser öffnen und prüfen, ob sich Paperless wie gewohnt verwenden lässt.
Schritt 20 – Datenbank abschließend prüfen
Zum Abschluss sollten Sie noch einmal überprüfen, ob der neue PostgreSQL-18-Container fehlerfrei läuft und Paperless erfolgreich mit der neuen Datenbank verbunden ist. Kontrollieren Sie zunächst den Status der Container und prüfen Sie anschließend die PostgreSQL-Version. Erscheint die PostgreSQL-18-Version, wurde das Upgrade erfolgreich abgeschlossen.
Wird die Ausgabe seitenweise dargestellt, können Sie diese mit der Taste q wieder verlassen.
Mit diesem Befehl werden alle Container des Docker-Compose-Projekts einschließlich ihres aktuellen Status angezeigt. So können Sie schnell überprüfen, ob der PostgreSQL-18-Datenbankcontainer sowie alle weiteren Paperless-Dienste fehlerfrei gestartet wurden:
docker compose ps
Mit diesem Befehl wird eine Verbindung zum PostgreSQL-Datenbankserver hergestellt und die installierte PostgreSQL-Version angezeigt. So können Sie schnell überprüfen, ob tatsächlich PostgreSQL 18 ausgeführt wird:
docker compose exec db psql -U paperless -c "SELECT version();"
Mit diesem Befehl wird eine Verbindung zur Datenbank paperless hergestellt und die verwendete PostgreSQL-Version ausgegeben. Damit überprüfen Sie, ob die Paperless-Datenbank erfolgreich auf dem PostgreSQL-18-Datenbankserver betrieben wird:
docker compose exec db psql -U paperless -d paperless -c "SELECT version();"
Geben alle Befehle die PostgreSQL-Version 18.x aus, wurde das Datenbank-Upgrade erfolgreich abgeschlossen. Sowohl der PostgreSQL-Datenbankserver als auch die Paperless-Datenbank werden nun unter PostgreSQL 18 betrieben.
Wichtige Informationen zu den Vollbackups der Paperless VM
Testen Sie Paperless nun in Ruhe und überprüfen Sie, ob sich die Dokumente öffnen, durchsuchen und bearbeiten lassen. In meiner eigenen Paperless-Instanz befinden sich mehr als 2.000 Dokumente, und nach dem Upgrade funktioniert weiterhin alles einwandfrei.
Löschen Sie das alte Datenbank-Volume von PostgreSQL 17 dennoch noch nicht. Lassen Sie es zunächst bestehen, damit Sie darauf zurückgreifen können, falls zu einem späteren Zeitpunkt doch noch Probleme auftreten.
Erstellen Sie nach dem erfolgreichen Upgrade außerdem erneut ein vollständiges Backup der virtuellen Maschine. Bewahren Sie nach Möglichkeit auch die letzten Vollbackups vor und nach dem Upgrade von Paperless 2.x auf Paperless 3.x sowie vor und nach dem Upgrade von PostgreSQL 17 auf PostgreSQL 18 längerfristig auf.
Ralf-Peter Kleinert / ComputerRalle
Ich verwende moderne KI-Systeme als unterstützendes Werkzeug, um meine Texte zu strukturieren, sprachlich zu überarbeiten und in eine verständliche Form zu bringen. Dabei nutze ich Künstliche Intelligenz unter anderem zur Korrektur von Rechtschreibung und Grammatik, zur besseren Gliederung von Inhalten sowie zur Optimierung von Formulierungen. Dennoch schreibe ich meine Inhalte zunächst komplett alleine – seit mehr als 20 Jahren! Auch verwende ich inzwischen KI-Systeme zum Erzeugen von Bildern für meine Webseiten oder Video-Thumbnails. In beiden Fällen ist dies für mich eine enorme Zeitersparnis, sodass ich mich stärker auf die eigentlichen Inhalte konzentrieren kann.