Daten
DatenFortgeschritten

PostgreSQL in Docker für Produktion: Volumes, Shared Memory, Pooling & Backups

PostgreSQL produktiv in Docker betreiben ohne Datenverlust und OOM: PG 18+ PGDATA-Pfadwechsel, shm_size, sauberes SIGTERM-Shutdown, PgBouncer-Pooling und getestete Backups.

Titelbild: PostgreSQL in Docker für Produktion: Volumes, Shared Memory, Pooling & Backups
Inhalt

PostgreSQL in Docker ist in zehn Sekunden gestartet — und in zehn Minuten verliert man damit in Produktion Daten, wenn man einfach ein Standard-Snippet aus einem Tutorial übernimmt.

Die meisten Ausfälle bei containerisiertem Postgres liegen nicht an Docker selbst. Sie entstehen, weil Dockers Standardwerte (64 MB /dev/shm, 10 Sekunden Timeout bis SIGKILL, ungepinnte :latest-Tags und veraltete PGDATA-Pfade) direkt mit dem Speicher-, Checkpoint- und Dateisystem-Modell von PostgreSQL kollidieren.

Die Kurz-Checkliste. Mounte PG-18+-Volumes unter /var/lib/postgresql (nicht /data), setze shm_size: 1gb+, setze stop_grace_period: 60s, aktiviere --data-checksums, schalte PgBouncer vor Lastspitzen und binde Port 5432 niemals an 0.0.0.0.

Produktive PostgreSQL-Architektur in Docker Compose mit PgBouncer-Pooling, getuntem Container, Named Volume und Offsite-Backups.
Ein produktionsreifes Docker-Compose-Setup trennt Ingress-Pooling (PgBouncer), sauber getuntes Container-Lifecycle-Management, lokale NVMe-Persistenz und Offsite-Backups.

Der Breaking Change ab PostgreSQL 18+: PGDATA-Mount-Pfad

Wer ein bestehendes Docker-Compose-Setup auf PostgreSQL 18 oder neuer hebt, stößt sofort auf die wichtigste strukturelle Änderung im offiziellen Image.

Vergleich der Docker-Volume-Pfade von PostgreSQL 17 vs. 18+ sowie die fünf häufigsten stillen Produktionsfehler.
Ab PostgreSQL 18 liegt PGDATA in versionsspezifischen Unterordnern unter /var/lib/postgresql, damit künftige pg_upgrade --link Upgrades reibungslos funktionieren.

Laut der offiziellen Docker-Hub-Dokumentation für postgres gilt:

  • PostgreSQL 17 und älter: PGDATA lag direkt in /var/lib/postgresql/data, Volumes wurden auf /var/lib/postgresql/data gemountet.
  • PostgreSQL 18 und neuer: PGDATA liegt jetzt in versionsspezifischen Unterordnern (/var/lib/postgresql/18/docker bzw. /19/docker für v19), und das definierte Docker-VOLUME ist /var/lib/postgresql.

Der Grund: Das Container-Layout entspricht damit Debians pg_ctlcluster-Konvention, sodass pg_upgrade --link künftige Major-Upgrades innerhalb desselben Überordners direkt vornehmen kann.

Sicheres Upgrade von PG ≤17 auf PG 18+ in 4 Befehlen

Lass das alte Volume als sofortiges Rollback unberührt, bis der neue Container verifiziert ist:

Terminal window
# 1. Alle Datenbanken und Rollen aus dem laufenden PG-17-Container sichern
docker exec -t pg-prod pg_dumpall -U app_admin > pg17_full.sql
# 2. Stack stoppen (KEIN -v übergeben, damit das alte PG-17-Volume erhalten bleibt)
docker compose down
# 3. compose.yaml auf postgres:18.1-bookworm + NEUES Volume unter /var/lib/postgresql umstellen und starten
docker compose up -d postgres
# 4. Dump in den frischen PG-18-Container einspielen
docker exec -i pg-prod psql -U app_admin -d postgres < pg17_full.sql

5 stille Produktionsfallen im Docker-Standard

1. Der 64-MB-/dev/shm-Absturz (shm_size)

Docker begrenzt /dev/shm standardmäßig auf 64 MB. PostgreSQL nutzt POSIX Shared Memory für Dynamic Shared Memory (DSM), Parallel Workers und parallele Hash-Joins. Unter Last brechen Queries plötzlich ab mit:

ERROR: could not resize shared memory segment "/PostgreSQL.12345" to 67108864 bytes: No space left on device

Lösung: Setze shm_size: 1gb (oder 2gb–4gb bei größeren Instanzen) explizit im Compose-Service.

2. Das 10-Sekunden-SIGKILL-Limit beim Stoppen

Bei docker compose down oder docker stop sendet Docker SIGTERM und wartet nur 10 Sekunden, bevor SIGKILL den Prozess hart beendet. Muss PostgreSQL gerade gigabyteweise Dirty Buffers in einen Checkpoint schreiben, reicht das nicht — beim nächsten Start läuft ein langsames Crash-Recovery über das WAL.

Lösung: Setze stop_grace_period: 60s (bei hoher Schreiblast 120s), damit PostgreSQL per SIGTERM (fast shutdown) seinen Checkpoint ordentlich abschließen kann.

3. Trügerische Healthchecks ohne -U und -d

Ein simples pg_isready ohne Parameter prüft den Standard-User (root) und kann während initdb-Neustarts bereits „healthy“ melden, bevor Zieldatenbank und App-User existieren.

Lösung: Immer User und Zieldatenbank übergeben:

healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
start_period: 20s

4. Verbindungs-Engpässe ohne Connection Pooler

PostgreSQL forkt für jede Client-Verbindung einen eigenen OS-Backend-Prozess (~5–10 MB RAM plus work_mem). Ein plötzlicher Ansturm von 300 Serverless- oder Worker-Verbindungen führt im speicherbegrenzten Container schnell zum Linux-OOM-Kill.

Lösung: Schalte PgBouncer im transaction-Pooling-Modus vor Postgres: max_connections bleibt schlank (z. B. 100–150), während PgBouncer 500+ Client-Verbindungen abfedert. Seit PgBouncer 1.21+ funktionieren Prepared Statements über MAX_PREPARED_STATEMENTS direkt im Transaction-Modus — ORMs wie Prisma, SQLAlchemy oder pgx brauchen keine Workarounds mehr.

5. Named Volumes vs. Bind Mounts & Rechte

  • Linux-Server: Sowohl ein Docker Named Volume auf lokalem NVMe-Storage als auch ein sauberes Host-Verzeichnis mit UID/GID 999:999 funktionieren sauber (niemals SMB/NFS ohne strikte Locking-Garantien).
  • Heimserver (Proxmox / TrueNAS / Mini-PC): Wenn du noch entscheidest, ob Docker direkt auf Linux, in einer Proxmox-KVM-VM oder auf TrueNAS läuft, schau in unseren Hardware-Guide Proxmox VE vs. Docker vs. TrueNAS Scale.

Produktionsreifes compose.yaml zum Kopieren (PostgreSQL 18+ + PgBouncer)

Ein sauberes Baseline-Setup mit Docker-Compose-Service-Optionen und PostgreSQL-Ressourcenparametern (dimensioniert für einen 8-GB-RAM-Host):

services:
postgres:
image: postgres:18.1-bookworm # Exakte Version pinnen, niemals :latest
container_name: pg-prod
restart: unless-stopped
stop_grace_period: 60s
shm_size: 1gb
environment:
POSTGRES_USER: app_admin
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set in .env}
POSTGRES_DB: app_prod
POSTGRES_INITDB_ARGS: "--data-checksums --encoding=UTF8 --locale=C.UTF-8"
command:
- "postgres"
- "-c"
- "shared_buffers=2GB"
- "-c"
- "effective_cache_size=6GB"
- "-c"
- "work_mem=16MB"
- "-c"
- "maintenance_work_mem=512MB"
- "-c"
- "max_connections=120"
- "-c"
- "wal_level=replica"
- "-c"
- "random_page_cost=1.1"
- "-c"
- "effective_io_concurrency=200"
volumes:
# PG 18+ mountet auf /var/lib/postgresql (fuer PG <=17 /var/lib/postgresql/data)
- pg_data:/var/lib/postgresql
networks:
- db_internal
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
start_period: 20s
logging:
driver: json-file
options:
max-size: "50m"
max-file: "5"
pgbouncer:
image: edoburu/pgbouncer:v1.24.1-p1
container_name: pg-pooler
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
environment:
DB_HOST: postgres
DB_PORT: 5432
DB_USER: app_admin
DB_PASSWORD: ${POSTGRES_PASSWORD:?set in .env}
DB_NAME: app_prod
POOL_MODE: transaction
MAX_CLIENT_CONN: 500
DEFAULT_POOL_SIZE: 30
MAX_PREPARED_STATEMENTS: 200
AUTH_TYPE: scram-sha-256
ports:
# Nur an localhost oder privates Tailscale/WireGuard-Interface binden — nie 0.0.0.0
- "127.0.0.1:6432:5432"
networks:
- db_internal
volumes:
pg_data:
networks:
db_internal:
driver: bridge

Zwei Details, die im Ernstfall den Unterschied machen:

  1. --data-checksums beim initdb erkennt stille Speicherfehler sofort, bevor sie unbemerkt in Backups wandern.
  2. Port 5432 wird gar nicht veröffentlicht, und PgBouncer lauscht ausschließlich auf 127.0.0.1:6432 (bzw. im internen Docker-Netzwerk).

Spickzettel für RAM-Sizing (2 GB bis 32 GB Server)

Das compose.yaml oben ist auf einen 8-GB-Host ausgelegt. Für kleinere oder größere Server skalierst du diese fünf Parameter proportional — PostgreSQL nutzt intensiv den Linux-OS-Page-Cache, daher bleiben bewusst ~50–75 % des RAMs außerhalb von shared_buffers:

Spickzettel für RAM-Sizing (2 GB bis 32 GB Server)
Host-RAM shm_size shared_buffers effective_cache_size work_mem max_connections
2 GB 512mb 512MB 1536MB 4MB 60
4 GB 1gb 1GB 3GB 8MB 80
8 GB 1gb 2GB 6GB 16MB 120
16 GB 2gb 4GB 12GB 32MB 150
32 GB 4gb 8GB 24GB 64MB 200

Backups & Recovery: Niemals ein laufendes Volume mit tar kopieren

Selbst wenn dein Host auf RAID oder ZFS läuft, gilt: RAID-Snapshots sind kein Disaster Recovery. Ein tar oder rsync auf ein laufendes PGDATA-Verzeichnis erzeugt inkonsistente Seiten und unbrauchbare Backups.

Zwei saubere Wege:

  1. Logische komprimierte Dumps (DBs unter ~30–50 GB): Regelmäßig pg_dump -Fc ausführen und verschlüsselt per restic oder rclone in S3-kompatiblen Storage ohne Egress-Kosten wie Cloudflare R2 sichern:
    Terminal window
    docker exec pg-prod pg_dump -U app_admin -Fc app_prod > /backups/app_prod_$(date +%F).dump
  2. Kontinuierliche WAL-Archivierung + PITR (größere DBs / enges RPO): Mit pgBackRest oder WAL-G im eigenen Image oder Sidecar für Point-in-Time-Recovery auf die Sekunde genau.

Teste einmal im Monat einen Restore in einen Wegwerf-Container — ein ungetestetes Backup ist nur Hoffnung:

Terminal window
# Test-Container starten, aktuellen Dump einspielen und wieder aufräumen
docker run -d --name pg-restore-test -e POSTGRES_PASSWORD=test -e POSTGRES_USER=app_admin -e POSTGRES_DB=app_prod postgres:18.1-bookworm
sleep 5
docker exec -i pg-restore-test pg_restore -U app_admin -d app_prod --no-owner < /backups/app_prod_$(date +%F).dump
docker rm -f pg-restore-test

Für die passende Index-Strategie in Postgres siehe außerdem unseren PostgreSQL-Index-Benchmark (B-Tree, GIN, BRIN).

Schnelle Diagnose: 3 Fehler direkt aus docker logs

  • Skipping initialization oder sofortiger Exit nach dem Update auf postgres:18: Ein PG-≤17-Volume wurde in ein PG-18+-Image gemountet. Image auf postgres:17 zurückdrehen, per pg_dumpall sichern und in ein neues Volume unter /var/lib/postgresql einspielen.
  • could not resize shared memory segment ... No space left on device: /dev/shm hat Dockers 64-MB-Limit erreicht. shm_size auf 1gb+ erhöhen und Container neu anlegen (docker compose up -d --force-recreate postgres).
  • chown: changing permissions ... Operation not permitted: Typisch bei Host-Bind-Mounts unter macOS/Windows oder Rootless-Docker. Auf ein Docker Named Volume (pg_data:/var/lib/postgresql) wechseln oder unter Linux chown -R 999:999 setzen.

Quellen

Häufig gestellte Fragen

Warum startet PostgreSQL 18 nicht mit meinem alten Docker-Volume unter /var/lib/postgresql/data?

Ab PostgreSQL 18 legt das offizielle Docker-Image PGDATA in versionsspezifischen Unterverzeichnissen (/var/lib/postgresql/18/docker) ab und erwartet das Volume unter /var/lib/postgresql, damit künftige pg_upgrade --link Läufe sauber funktionieren. Richte postgres:18 niemals direkt auf ein PG-17-Volume — erstelle mit pg_dumpall einen Dump und spiele ihn in ein neues Volume unter /var/lib/postgresql ein.

Wie viel shm_size braucht PostgreSQL in Docker?

Docker begrenzt /dev/shm standardmäßig auf 64 MB — deutlich zu wenig für PostgreSQL Parallel Workers und Dynamic Shared Memory. Setze shm_size mindestens auf 1gb für kleine Produktiv-Instanzen und auf 2gb–4gb bei shared_buffers über 2 GB.

Sollte ich für PostgreSQL ein Docker Named Volume oder einen Bind Mount nutzen?

Auf Linux-Servern funktionieren sowohl Docker Named Volumes auf lokalem NVMe/SSD als auch ein sauberes Host-Verzeichnis (niemals SMB/NFS ohne strikte Locking-Garantien). Auf macOS und Windows solltest du immer ein Named Volume innerhalb der Linux-VM nutzen, um massive I/O-Verluste und Rechtefehler zu vermeiden.

Ist PostgreSQL in Docker für Produktion sicher?

Ja — wenn es sauber konfiguriert ist: exaktes Image-Tag pinnen, lokales Persistenz-Volume nutzen, shm_size erhöhen, stop_grace_period: 60s setzen, Port 5432 nicht öffentlich freigeben, PgBouncer vorschalten und Backups verschlüsselt offsite sichern.

Wie sichere ich PostgreSQL in Docker ohne Downtime?

Für Datenbanken unter ~20–50 GB eignet sich pg_dump -Fc per Cron/Sidecar mit verschlüsseltem Upload in S3-kompatiblen Storage (z. B. Cloudflare R2). Für größere Datenbanken oder strenge RPO-Ziele liefern WAL-G oder pgBackRest kontinuierliche WAL-Archivierung und Point-in-Time-Recovery (PITR).

Aus der Community

Diskussion auf Mastodon & Bluesky

Antworten auf diesen Artikel aus dem offenen Netz, live geladen. Keine Werbung, keine Tracking-Skripte.

Antworten werden geladen …
Auf Mastodon antwortenAuf Bluesky antworten

Antworte dort — es erscheint hier automatisch.

ENDE