DEV Community

Aleksei Aleinikov
Aleksei Aleinikov

Posted on Originally published at alekseialeinikov.com on

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

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

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.

Achtung

Richte postgres:18 niemals auf ein bestehendes PG-17-Volume. Major-Versionen sind auf Dateiebene nicht kompatibel, und der Container verweigert den Start. Erstelle im laufenden PG-17-Container ein pg_dumpall, lege ein neues Named Volume unter /var/lib/postgresql an und spiele den Dump dort sauber ein.

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 sicherndocker 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 startendocker compose up -d postgres
# 4. Dump in den frischen PG-18-Container einspielendocker exec -i pg-prod psql -U app_admin -d postgres < pg17_full.sql
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

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
Enter fullscreen mode Exit fullscreen mode
  1. 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äumendocker run -d --name pg-restore-test -e POSTGRES_PASSWORD=test -e POSTGRES_USER=app_admin -e POSTGRES_DB=app_prod postgres:18.1-bookwormsleep 5docker exec -i pg-restore-test pg_restore -U app_admin -d app_prod --no-owner < /backups/app_prod_$(date +%F).dumpdocker rm -f pg-restore-test
Enter fullscreen mode Exit fullscreen mode

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

Ursprünglich veröffentlicht auf alekseialeinikov.com

Top comments (0)