Data
DataIntermediate

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

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.

Cover image: PostgreSQL in Docker for Production: Volumes, Shared Memory, Pooling & Backups
Contents

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.

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

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

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:

Terminal window
# 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:

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:

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

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

Here is a clean, battle-tested baseline using Docker Compose service controls and PostgreSQL resource settings (example sized for an 8 GB RAM host):

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:

Memory Sizing Cheat Sheet (2 GB to 32 GB Hosts)
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. 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 via restic or rclone:
    Terminal window
    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:

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

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

Frequently asked questions

Why does PostgreSQL 18 fail to start with my old Docker volume at /var/lib/postgresql/data?

Starting in PostgreSQL 18, the official Docker image moved PGDATA into versioned subdirectories (/var/lib/postgresql/18/docker) and changed the target VOLUME mount point to /var/lib/postgresql so future pg_upgrade --link runs work cleanly. Never point postgres:18 directly at a PG 17 volume — dump with pg_dumpall from PG 17 and restore into a fresh PG 18 volume mounted at /var/lib/postgresql.

How much shm_size should I allocate to PostgreSQL in Docker?

Docker defaults /dev/shm to 64 MB, which is far too small for PostgreSQL parallel workers and dynamic shared memory segments. Set shm_size to at least 1gb for small production instances and 2gb–4gb when shared_buffers exceeds 2 GB.

Should I use a Docker named volume or a bind mount for PostgreSQL?

On Linux servers, either a Docker named volume on local NVMe/SSD or a clean host directory bind mount works well (never use a network share like SMB/NFS without strict locking guarantees). On macOS or Windows, always use a named volume inside the Linux VM rather than a host bind mount to avoid severe I/O overhead and file-permission corruption.

Is running PostgreSQL in Docker safe for production?

Yes — when configured intentionally. Pin the exact image tag, mount a persistent local volume, raise shm_size, set stop_grace_period: 60s, isolate port 5432 from the public internet, pool connections with PgBouncer, and ship encrypted backups off-host.

How do I back up PostgreSQL running inside Docker without downtime?

For databases under ~20–50 GB, run scheduled pg_dump -Fc inside an exec or sidecar job and ship encrypted dumps to S3-compatible storage (such as Cloudflare R2). For larger databases or tight RPO requirements, use WAL-G or pgBackRest for continuous WAL archiving and Point-in-Time Recovery (PITR).

From the community

Discussion on Mastodon & Bluesky

Replies to this article from the open web, pulled in live. No ads, no tracking scripts.

Loading replies …
Reply on MastodonReply on Bluesky

Reply there — it shows up here automatically.

ENDE