Schritt-für-Schritt-Anleitung für das PostgreSQL Update auf Version.16 mit vollständiger Datenmigration. z.Z. die Empfohlene Version.
Hinweise:
– Alle Befehle in diesem Leitfaden sind für die Windows-Eingabeaufforderung (CMD) optimiert.
– Überprüfe vor dem Update ob PostgreSQL Version 16 für deine Anwendung kompatibel ist.
– In diesem Beispiel arbeiten wir mit „Immich Foto“, Container Namen und der Container der Datenbank muss du an deine Umgebung anpassen.
🎯 Was Sie erwartet
Dieses Upgrade führt Ihre PostgreSQL-Datenbank von Version 14 auf die empfohlene Version 16 durch. Neben der reinen Version wird auch die Vektor-Erweiterung von pgvecto.rs auf VectorChord aktualisiert – die aktuelle PostgreSQL-Standardmethode mit deutlichen Leistungsverbesserungen für Vektoroperationen.
Der Prozess verwendet eine logische Sicherung und Wiederherstellung (pg_dumpall / psql), die als sicherste Methode für Major-Upgrades gilt.
Besonderheiten in diesem Guide:
- Erklärung der kritischen
shm_size-Einstellung für PostgreSQL 16 - Warum
POSTGRES_INITDB_ARGS: '--data-checksums'Ihre Daten schützt - Fehlerbehandlung bei häufigen Problemen
📋 Voraussetzungen
- Laufende PostgreSQL-Installation mit Docker Compose
- Ausreichend freier Festplattenspeicher (mindestens Größe der aktuellen Datenbank + 20%)
- Zugriff auf die Konsole des Docker-Hosts
Video: PostgreSQL Update auf Version.16, Major Upgrade inks. Datenübernahme
Sprache: 🇩🇪|🇬🇧
☝️ Benutze YouTube Untertitel für alle Sprachen.
🔧 Schritt 1: Docker-Compose-Datei vorbereiten
Öffnen Sie Ihre docker-compose.yml und ersetzen Sie den bestehenden PostgreSQL-Service:
ALTER Service (PostgreSQL 14 mit pgvecto.rs):
yaml
db:
image: postgres:14
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: ${DB_USERNAME}
POSTGRES_DB: ${DB_DATABASE_NAME}
volumes:
- ${DB_DATA_LOCATION}:/var/lib/postgresql/data
restart: always
NEUER Service (PostgreSQL 16 mit VectorChord):
yaml
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: ${DB_USERNAME}
POSTGRES_DB: ${DB_DATABASE_NAME}
POSTGRES_INITDB_ARGS: '--data-checksums'
volumes:
- ${DB_DATA_LOCATION}:/var/lib/postgresql/data
restart: always
shm_size: 128mb
Speichern Sie die Datei.
🛑 Schritt 2: Abhängige Dienste stoppen
Stoppen Sie alle Dienste, die auf die Datenbank zugreifen:
cmd
docker compose stop immich-server immich-machine-learning redis
Passen Sie die Service-Namen an Ihre Umgebung an.
💾 Schritt 3: Datenbank-Backup erstellen
Erstellen Sie ein vollständiges Backup:
cmd
docker exec immich_postgres pg_dumpall -c -U postgres > immich_backup.sql
Prüfen Sie, ob das Backup erfolgreich war:
cmd
dir immich_backup.sql
Die Datei sollte eine angemessene Größe haben (nicht 0 Bytes).
🗑️ Schritt 4: Alten Datenbank-Container entfernen
cmd
docker compose down db
Der alte Container wird gelöscht, Ihre Daten im Volume bleiben jedoch erhalten.
🚨 Schritt 5: Datenbank-Volume leeren (kritisch!)
Der neue PostgreSQL 16-Container kann nicht mit alten PostgreSQL 14-Daten starten. Sie müssen das Volume leeren:
Zuerst prüfen, wo Ihre Daten liegen:
cmd
type .env | findstr DB_DATA_LOCATION
Abhängig vom Pfadtyp:
Fall 1 – Relativer Pfad (beginnt mit . oder ./):
cmd
rmdir /s /q postgres
Fall 2 – Absoluter Pfad (z.B. D:\DockerData\postgres):
cmd
rmdir /s /q D:\DockerData\postgres
Fall 3 – Docker-Volume:
cmd
docker volume ls docker volume rm HIER_DEN_VOLUME_NAMEN_EINFÜGEN
⚠️ Achtung: Dieser Schritt löscht die alten PostgreSQL 14-Daten. Stellen Sie sicher, dass Ihr Backup aus Schritt 3 existiert!
🚀 Schritt 6: Neuen PostgreSQL 16-Container starten
cmd
docker compose up -d db
Der Container initialisiert nun ein leeres Datenbank-Cluster mit PostgreSQL 16 und VectorChord, inklusive:
- Data Checksums (durch
--data-checksums) - Erhöhtem Shared Memory (durch
shm_size: 128mb)
Prüfen Sie, ob der Container läuft:
cmd
docker ps | findstr postgres
Die Ausgabe sollte den Container mit Status Up zeigen.
Bei Problemen: Container-Logs prüfen:
cmd
docker logs immich_postgres --tail 50
📥 Schritt 7: Backup in die neue Datenbank importieren
cmd
docker exec -i immich_postgres psql -U postgres < immich_backup.sql
Dieser Vorgang kann je nach Datenbankgröße mehrere Minuten dauern. Nicht unterbrechen!
Hinweis: Bei sehr großen Datenbanken kann der Import eine Stunde oder länger dauern – das ist normal.
🔄 Schritt 8: Alle Dienste neu starten
cmd
docker compose up -d
✅ Schritt 9: Erfolgskontrolle
Prüfen Sie die PostgreSQL-Version:
cmd
docker exec immich_postgres psql -U postgres -c "SHOW server_version;"
Erwartete Ausgabe: 16.x (nicht 14.x)
Prüfen Sie, ob Checksums aktiviert sind:
cmd
docker exec immich_postgres psql -U postgres -c "SELECT datname, datchecksum FROM pg_database;"
Prüfen Sie die Logs auf Fehler:
cmd
docker compose logs --tail 50
❓ Die zwei wichtigen Sonderfragen – erklärt
1. Warum shm_size: 128mb?
Shared Memory (/dev/shm) ist ein temporärer Speicherbereich, den PostgreSQL für parallele Abfragen und Vektoroperationen nutzt.
Das Problem: Docker weist standardmäßig nur 64 MB zu – für PostgreSQL 16 zu wenig.
Die Folgen ohne diese Einstellung:
text
ERROR: could not resize shared memory segment FATAL: could not create shared memory segment
Die Lösung: Mit shm_size: 128mb erhalten Sie ausreichend Shared Memory. Bei sehr großen Datenbanken (>50.000 Einträge) empfehlen sich 256 MB oder 512 MB.
2. Was bewirkt POSTGRES_INITDB_ARGS: '--data-checksums'?
Dies aktiviert Prüfsummen für jede Datenseite in PostgreSQL.
Vorteile:
- Erkennung von stiller Datenkorruption (defekte Festplatten, Bitrot, RAM-Fehler)
- Frühwarnsystem statt unbemerkt falscher Daten
- Ermöglicht gezielte Wiederherstellung aus Backups
Die Kosten: Nur 2-3% Performance-Overhead – für die meisten Anwendungen völlig akzeptabel.
Wichtig: Dies wirkt nur bei der ersten Initialisierung der Datenbank – genau das passiert bei diesem Upgrade.
🚨 Fehlerbehandlung
Fehler: „Container is restarting“
Ursache: Der Container kann nicht starten, meist wegen inkompatibler alter Daten.
Lösung:
- Container stoppen:
docker compose down db - Volume leeren (siehe Schritt 5)
- Container neu starten:
docker compose up -d db - Backup erneut importieren
Fehler: „psql: could not connect to server“
Ursache: Der PostgreSQL-Server läuft nicht.
Lösung:
cmd
docker ps -a | findstr postgres docker logs immich_postgres --tail 50
Die Logs zeigen die genaue Ursache.
Fehler: „permission denied“ beim Import
Ursache: Berechtigungsprobleme im Container.
Lösung:
cmd
docker exec -i immich_postgres psql -U postgres -f - < immich_backup.sql
📊 Nach dem Upgrade
Empfohlene Aktionen:
- Backup aufbewahren – löschen Sie
immich_backup.sqlerst nach erfolgreichem Betrieb - Leistung beobachten – die ersten Stunden werden Indizes neu aufgebaut
- Regelmäßige Backups einrichten – nutzen Sie jetzt die Vorteile der Checksums
🎓 Fazit
Das Major-Upgrade von PostgreSQL 14 auf 16 ist mit diesem Verfahren sicher und sauber. Die Kombination aus:
- Logischem Backup (
pg_dumpall) - Gereinigtem Datenbank-Volume
- Wechsel von pgvecto.rs zu VectorChord
- Zusätzlichen Optimierungen (
shm_size,data-checksums)
macht Ihre Datenbank zukunftssicher und robuster gegen Datenkorruption.
Wichtiger Hinweis: Nach diesem Upgrade können Sie nicht einfach zum alten Container zurückkehren – die Datenbankstruktur ist nicht abwärtskompatibel. Ein Rollback wäre nur durch Einspielen des alten Backups auf einem PostgreSQL 14-Container möglich.
Link zur Unterstützung / Spende für den Kanal
Wenn meine Beiträge hilfreich sind oder dir geholfen haben, würde ich mich über eine Unterstützung sehr freuen 🙏
#PostgreSQL16 #PostgreSQLUpdate #MajorUpgrade #DatabaseMigration #DockerPostgreSQL #VectorChord #pgvectors
