---
title: "PostgreSQL in Docker für Produktion: Volumes, Shared Memory, Pooling & Backups"
description: "PostgreSQL produktiv in Docker betreiben ohne Datenverlust und OOM: PG 18+ PGDATA-Pfadwechsel, shm_size, sauberes SIGTERM-Shutdown, PgBouncer-Pooling und getestete Backups."
author: Aleksei Aleinikov
date: 2026-11-17
lang: de
tags: [postgresql docker, postgres docker compose, postgresql 18 docker pgdata, postgres docker shm_size, pgbouncer docker compose, postgres docker backup, postgresql produktion docker]
canonical: https://www.alekseialeinikov.com/de/blog/topics/data/postgresql-in-docker-produktion
source: alekseialeinikov.com
---

# 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.

> [!KEY]
> **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.](https://www.alekseialeinikov.com/blog/postgresql-in-docker-architecture.webp "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.](https://www.alekseialeinikov.com/blog/postgresql-in-docker-pgdata-upgrade.webp "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`](https://hub.docker.com/_/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.

> [!WARNING]
> **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:

```bash
# 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:

```text
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:

```yaml
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](https://www.pgbouncer.org/config.html)** 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](https://www.alekseialeinikov.com/de/blog/topics/lab/proxmox-vs-docker-vs-truenas-scale-heimserver).

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

Ein sauberes Baseline-Setup mit [Docker-Compose-Service-Optionen](https://docs.docker.com/compose/compose-file/05-services/) und [PostgreSQL-Ressourcenparametern](https://www.postgresql.org/docs/current/runtime-config-resource.html) (dimensioniert für einen 8-GB-RAM-Host):

```yaml
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`:

| 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](https://www.alekseialeinikov.com/de/blog/topics/cloud/backups-sind-kein-disaster-recovery-2026). 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](https://www.alekseialeinikov.com/de/blog/topics/cloud/cloudflare-r2-vs-s3-egress-kosten-2026) sichern:
   ```bash
   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:

```bash
# 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)](https://www.alekseialeinikov.com/de/blog/topics/data/postgresql-indizes-welcher-typ-wann-benchmark).

## 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

- [Docker Hub Official Image — `postgres` Dokumentation & PG-18+-`PGDATA`-Layout](https://hub.docker.com/_/postgres)
- [PostgreSQL Offizielle Dokumentation — Resource Consumption (`shared_buffers`, `work_mem`, DSM)](https://www.postgresql.org/docs/current/runtime-config-resource.html)
- [PgBouncer Offizielle Dokumentation — Konfiguration & Pooling-Modi](https://www.pgbouncer.org/config.html)
- [Docker Compose Spezifikation — Services (`shm_size`, `stop_grace_period`, `healthcheck`)](https://docs.docker.com/compose/compose-file/05-services/)
