---
title: "PostgreSQL in Docker for Production: Volumes, Shared Memory, Pooling & Backups"
description: "How to run PostgreSQL in Docker for production without losing data or hitting OOM: PG 18+ PGDATA volume path changes, shm_size sizing, graceful SIGTERM shutdown, PgBouncer pooling, and backups."
author: Aleksei Aleinikov
date: 2026-11-17
lang: en
tags: [postgresql docker, postgres docker compose, postgresql 18 docker pgdata, postgres docker shm_size, pgbouncer docker compose, postgres docker backup, postgresql production docker]
canonical: https://www.alekseialeinikov.com/en/blog/topics/data/postgresql-in-docker-production
source: alekseialeinikov.com
---

# PostgreSQL in Docker for Production: Volumes, Shared Memory, Pooling & Backups

Running **PostgreSQL in Docker** takes ten seconds to start in development — and about ten minutes to lose data in production if you copy a default `compose.yaml` snippet from a tutorial.

Most outages with containerized Postgres are not caused by Docker itself. They happen because Docker's defaults (64 MB `/dev/shm`, a 10-second `SIGKILL` timeout, unpinned `:latest` tags, and outdated `PGDATA` volume paths) collide directly with how PostgreSQL manages memory, checkpoints, and disk files.

> [!KEY]
> **The short checklist.** Mount **PG 18+** volumes at `/var/lib/postgresql` (not `/data`), set `shm_size: 1gb`+, set `stop_grace_period: 60s`, enable `--data-checksums`, put **PgBouncer** in front of bursts, and never expose port `5432` on `0.0.0.0`.

![Production PostgreSQL architecture in Docker Compose showing PgBouncer pooling, pinned container tuning, named volume persistence, and offsite backups.](https://www.alekseialeinikov.com/blog/postgresql-in-docker-architecture.webp "A production-safe Docker Compose layout separates ingress pooling (PgBouncer), tuned container memory/lifecycle, local NVMe persistence, and offsite backups.")

## The Breaking Change in PostgreSQL 18+: `PGDATA` Mount Path

If you upgrade an older Docker Compose stack to **PostgreSQL 18 or newer**, the very first trap is structural.

![PostgreSQL 17 vs. PostgreSQL 18+ Docker volume mount layout and the top five silent production failure modes.](https://www.alekseialeinikov.com/blog/postgresql-in-docker-pgdata-upgrade.webp "PostgreSQL 18+ moved PGDATA into versioned subdirectories under /var/lib/postgresql so future pg_upgrade --link runs work natively.")

Per the [official Docker Hub `postgres` image documentation](https://hub.docker.com/_/postgres):

- **PostgreSQL 17 and earlier:** `PGDATA` defaulted to `/var/lib/postgresql/data`, and Compose files mounted volumes to `/var/lib/postgresql/data`.
- **PostgreSQL 18 and newer:** `PGDATA` moved into version-specific subdirectories (`/var/lib/postgresql/18/docker`, and `/19/docker` for v19), and the official `VOLUME` target changed to **`/var/lib/postgresql`**.

Why did the maintainers make this breaking change? It aligns the container layout with Debian's `pg_ctlcluster` convention so `pg_upgrade --link` can upgrade major versions cleanly inside the same parent directory in the future.

> [!WARNING]
> **Never point `postgres:18` at an existing PG 17 volume.** Major versions are not binary-compatible on disk, and the new mount layout will refuse to start. Dump with `pg_dumpall` from your running PG 17 container, create a **new** named volume mounted at `/var/lib/postgresql`, and restore into the fresh PG 18 container.

### Safe PG ≤17 to PG 18+ Upgrade in 4 Commands

Keep your old volume untouched as an instant rollback until the new container is verified:

```bash
# 1. Dump all databases and roles from the running PG 17 container
docker exec -t pg-prod pg_dumpall -U app_admin > pg17_full.sql

# 2. Stop the stack (do NOT pass -v so the old PG 17 volume stays intact)
docker compose down

# 3. Update compose.yaml to postgres:18.1-bookworm + a NEW volume at /var/lib/postgresql, then start
docker compose up -d postgres

# 4. Restore into the fresh PG 18 container
docker exec -i pg-prod psql -U app_admin -d postgres < pg17_full.sql
```

## 5 Silent Production Traps in Default Docker Setups

### 1. The 64 MB `/dev/shm` Crash (`shm_size`)
Docker caps `/dev/shm` at **64 MB** by default. PostgreSQL uses POSIX shared memory for dynamic shared memory (DSM) segments, parallel query workers, and parallel hash joins. Under real load, queries abruptly fail with:

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

**Fix:** Explicitly allocate **`shm_size: 1gb`** (or `2gb`–`4gb` on larger nodes) in your Compose service.

### 2. The 10-Second `SIGKILL` Shutdown Trap
When you run `docker compose down` or `docker stop`, Docker sends `SIGTERM` and waits just **10 seconds** before sending `SIGKILL`. If PostgreSQL has gigabytes of dirty buffers to flush during a checkpoint, 10 seconds is not enough — Docker kills the process mid-flush, forcing slow WAL crash recovery on startup.

**Fix:** Set **`stop_grace_period: 60s`** (or `120s` for write-heavy instances) so Postgres receives `SIGTERM` (*fast shutdown*) and completes its checkpoint cleanly.

### 3. Broken Healthchecks (`pg_isready` False Positives)
Writing `test: ["CMD-SHELL", "pg_isready"]` without flags checks the default user (`root`) and database, and can pass briefly during `initdb` restarts before your actual database and role exist.

**Fix:** Always specify both user and target database:

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

### 4. Connection Exhaustion Without a Pooler
Unlike thread-based engines, PostgreSQL forks a dedicated OS backend process for every client connection (~5–10 MB RAM each plus `work_mem` headroom). A sudden burst of 300 serverless functions or worker containers can easily trigger a Linux OOM kill inside a memory-bounded container.

**Fix:** Place **[PgBouncer](https://www.pgbouncer.org/config.html)** in front of Postgres in **`transaction` pooling mode**, keeping `max_connections` on Postgres reasonable (e.g., `100–150`) while PgBouncer absorbs `500+` client connections. Since PgBouncer 1.21+, protocol-level prepared statements work natively in transaction mode via `MAX_PREPARED_STATEMENTS`, so ORMs like Prisma, SQLAlchemy, and `pgx` no longer need special workarounds.

### 5. Named Volumes vs. Bind Mounts & Permissions
- **Linux production hosts:** Prefer a **Docker named volume** on fast local NVMe SSD, or a dedicated host path owned by UID/GID `999:999` (Debian-based `postgres` image). Never place `PGDATA` on an SMB/CIFS network share.
- **Home servers (Proxmox / TrueNAS / Mini PC):** If you are deciding whether to run Docker directly on Linux, inside a Proxmox KVM VM, or on TrueNAS Scale, check our hardware-to-stack guide on [Proxmox VE vs. Docker vs. TrueNAS Scale](https://www.alekseialeinikov.com/en/blog/topics/lab/proxmox-vs-docker-vs-truenas-scale-home-server).

## Copy-Paste Production `compose.yaml` (PostgreSQL 18+ + PgBouncer)

Here is a clean, battle-tested baseline using [Docker Compose service controls](https://docs.docker.com/compose/compose-file/05-services/) and [PostgreSQL resource settings](https://www.postgresql.org/docs/current/runtime-config-resource.html) (example sized for an 8 GB RAM host):

```yaml
services:
  postgres:
    image: postgres:18.1-bookworm # Pin exact version; never use :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+ mounts to /var/lib/postgresql (for PG <=17 use /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:
      # Bind strictly to localhost or private Tailscale/WireGuard IP — never 0.0.0.0
      - "127.0.0.1:6432:5432"
    networks:
      - db_internal

volumes:
  pg_data:

networks:
  db_internal:
    driver: bridge
```

Notice two subtle details that save production teams hours later:
1. **`--data-checksums`** is enabled at `initdb` time so PostgreSQL catches silent storage bitrot immediately instead of silently replicating corruption into backups.
2. **Port `5432` is not published at all**, and PgBouncer is bound strictly to `127.0.0.1:6432` (or an internal bridge network for your app containers).

### Memory Sizing Cheat Sheet (2 GB to 32 GB Hosts)

The `compose.yaml` above targets an 8 GB node. If your server is smaller or larger, scale these five settings proportionally — PostgreSQL relies heavily on the Linux OS page cache, so leaving ~50–75% of RAM outside `shared_buffers` is intentional:

| 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 & Disaster Recovery: Never `tar` a Live Volume

Even if your Docker host sits on RAID or ZFS, [RAID snapshots are not disaster recovery](https://www.alekseialeinikov.com/en/blog/topics/cloud/backups-are-not-disaster-recovery-2026). Copying raw `PGDATA` files with `tar` or `rsync` while PostgreSQL is running captures torn pages and produces an unrecoverable backup.

Pick one of two clean backup patterns:

1. **Logical compressed dumps (DBs under ~30–50 GB):**
   Run `pg_dump -Fc` inside a scheduled container or cron job, verify exit status, and ship encrypted archives to [low-cost S3-compatible storage such as Cloudflare R2](https://www.alekseialeinikov.com/en/blog/topics/cloud/cloudflare-r2-vs-s3-egress-costs-2026) via `restic` or `rclone`:
   ```bash
   docker exec pg-prod pg_dump -U app_admin -Fc app_prod > /backups/app_prod_$(date +%F).dump
   ```
2. **Continuous WAL archiving + PITR (larger DBs or low RPO):**
   Use **pgBackRest** or **WAL-G** inside a custom PostgreSQL image or sidecar sharing the volume so you can restore to any exact second before a bad migration.

Once a month, prove your backups actually restore using a disposable scratch container — an untested backup is just hope:

```bash
# Spin up an ephemeral test container, restore the latest dump, and verify row counts
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
```

If you are also optimizing indexes or vector workloads inside Postgres, see our [PostgreSQL Index Types Benchmark](https://www.alekseialeinikov.com/en/blog/topics/data/postgres-index-types-which-to-use-btree-gin-brin-benchmark).

## Quick Troubleshooting: 3 Errors You Will Actually See

- **`Skipping initialization` or immediate exit after upgrading to `postgres:18`:** You mounted a PG ≤17 volume into a PG 18+ image. Roll back the image tag to `postgres:17`, dump with `pg_dumpall`, and restore into a new volume mounted at `/var/lib/postgresql`.
- **`could not resize shared memory segment ... No space left on device`:** `/dev/shm` hit Docker's 64 MB ceiling. Increase `shm_size` to `1gb`+ and recreate the container (`docker compose up -d --force-recreate postgres`).
- **`chown: changing permissions ... Operation not permitted`:** Typical when using a host bind mount on macOS/Windows or strict rootless UID mapping. Switch to a Docker named volume (`pg_data:/var/lib/postgresql`) or `chown -R 999:999` on Linux host paths.

## Sources

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