PostgreSQL in containers: what a container does not solve · PostgreSQL

Every measurement in this course was taken in a container. That is a reasonable way to run PostgreSQL, and it introduces a specific set of traps — most of which this course walked into while producing its own evidence.

What a container changes

Packaging. One image, the same everywhere, with the version pinned.

Isolation. Resource limits, network namespace, filesystem namespace.

Lifecycle. Start, stop and restart become orchestration events rather than service-manager events.

What it does not change

Everything in Parts VI to XVII. Storage, MVCC, vacuum, locks, the planner, memory, WAL, backups, replication, upgrades — a container is still running the same PostgreSQL, and every measurement in those parts was taken inside one.

Memory reporting is wrong inside a container

Read-only / Safewhat free reports inside a limited container— Captured on 18.6. The container's limit is much smaller than this.

$ free -m

(reported the host's 47 GB of memory, not the container's limit)

/proc/meminfo is not namespaced, so every tool that reads it — free, top, most monitoring agents — reports the host’s memory regardless of the cgroup limit.

The consequences:

Monitoring is wrong, and reports plenty of memory available right up to the moment the container is killed.
Anything auto-sizing from detected memory is wrong, which includes a great deal of tuning advice and some tooling.
The OOM killer acts on the cgroup limit, not on what free showed — lesson XI-06’s subject.

Read the cgroup instead:

cat /sys/fs/cgroup/memory.max        # the limit  (cgroup v2)
cat /sys/fs/cgroup/memory.current    # current usage

And size shared_buffers, work_mem and max_connections against that number, using lesson XI-01’s arithmetic.

Signals and PID 1

PostgreSQL’s shutdown modes from lesson XII-07 map onto signals: SIGTERM is smart, SIGINT is fast, SIGQUIT is immediate.

A container runtime sends SIGTERM on stop, waits, then SIGKILL. SIGTERM is the smart shutdown — which lesson XII-07 measured failing after 10 seconds while sessions remained connected, with pg_ctl: server does not shut down.

The default stop timeout can turn every stop into a crash

Smart shutdown waits for clients to disconnect. Docker’s default --stop-timeout is 10 seconds. On a cluster with connected clients:

SIGTERM arrives. Smart shutdown begins, refusing new connections and waiting for existing ones.
Ten seconds pass. Clients are still connected.
SIGKILL arrives.
The cluster crashes and performs recovery on next start.

Lesson XII-06 established that crash recovery is safe and correct — 300,000 committed rows survived a SIGKILL. But a crash on every stop means a recovery on every start, and on a large cluster with a dirty buffer pool that is real downtime added to every deployment.

The official image handles this: it sets STOPSIGNAL SIGINT, so a stop performs a fast shutdown. If you build your own image, set it — and raise the stop timeout to something longer than a checkpoint takes.

Data persistence

Never keep data in the container’s writable layer. It is destroyed with the container.

This course met the consequence directly. A docker commit of a PostgreSQL container captured no data at all, because the image declares /var/lib/postgresql as a volume and commit does not include volume contents:

Read-only / Safewhat a commit of a PostgreSQL container contains— Real error from this course's own work, while trying to snapshot a cluster for a pg_rewind demonstration.

$ docker commit rbpg-prim rbpg-prim-snap && docker run ... rbpg-prim-snap pg_controldata $PGDATA

pg_controldata: error: could not open file
"/var/lib/postgresql/18/docker/global/pg_control" for reading:
No such file or directory

The fix was to mount the original volume into the new container by name. The general rule: the volume is the database; the container is disposable.

Configuration precedence

The official image is started with -c setting=value command-line arguments. Lesson XIII-05 measured the consequence:

Read-only / SafeALTER SYSTEM writing the file, reporting success, and changing nothing— Captured on 18.6 in the official container image.

$ SELECT name, setting, source FROM pg_settings WHERE name = 'archive_command';

      name       |                  setting                   |    source
-----------------+--------------------------------------------+--------------
archive_command | test ! -f /archive/%f && cp %p /archive/%f | command line

ALTER SYSTEM wrote postgresql.auto.conf and reported success. The setting did not change, because command-line arguments outrank it.

Always confirm with pg_settings.source, not with the file contents. This is a container-specific hazard precisely because the official image uses command-line arguments as its configuration mechanism.

What still needs solving

A container gives you none of:

Backups. Part XIII.
Replication and failover. Parts XIV and XV.
Monitoring. Part XVI.
Storage durability — an image says nothing about whether the volume’s fsync is honest. Lesson VI-01.
Connection pooling. Lesson IV-06.

Why the container ecosystem's defaults fit PostgreSQL badly

Containers were designed around stateless, horizontally scalable, disposable processes. PostgreSQL is stateful, vertically scaled and emphatically not disposable, and several defaults follow from the first model in ways that hurt the second.

Restart policies assume restarting helps. A container that exits is restarted, possibly in a loop. A PostgreSQL cluster that exits because pg_wal is full — lesson XVII-02 — is restarted into the same condition, repeatedly, and each attempt performs crash recovery and fails. The restart loop obscures the error rather than fixing it, and the useful log line scrolls past between attempts.

Health checks assume a shallow answer. pg_isready reports whether the postmaster accepts connections, which is true of a cluster that is in recovery, refusing writes, or serving from a corrupted page. A health check that runs an actual query, on an actual table, is a different and more useful statement.

Resource limits interact badly with shared memory. shared_buffers is allocated at startup and counts against the cgroup limit. A limit set below shared_buffers plus per-connection memory produces an OOM kill at some unpredictable connection count rather than a clean refusal at startup, which is lesson XI-06’s failure mode with a container-shaped trigger.

Image immutability fights configuration. The natural container pattern is to bake configuration into the image or pass it as environment. PostgreSQL’s configuration is a file the server rewrites — postgresql.auto.conf — and reconciling those two models is what produces the command-line-argument precedence trap above.

None of this argues against containers, and this course used them throughout precisely because they made every measurement reproducible and disposable. It argues for treating a database container as a long-lived stateful service that happens to be packaged as a container, rather than as a container that happens to run a database. The defaults encode the second assumption.

What to take from this

A container changes packaging, isolation and lifecycle. It changes nothing about PostgreSQL’s behaviour.
free reports the host’s memory. Read /sys/fs/cgroup/memory.max and size from that.
SIGTERM is the smart shutdown, which can fail to complete. Set STOPSIGNAL SIGINT and a generous stop timeout, or every stop is a crash.
The volume is the database. docker commit captures no volume data — measured.
The official image configures via command-line arguments, which outrank ALTER SYSTEM. Check pg_settings.source.
Containers give you no backups, replication, monitoring, durable storage or pooling.

Cross-course references

Docker & Containers — Part VIII (Storage) covers volume lifetime against container lifetime, Part VI (Container lifecycle) covers the stop-then-kill sequence that makes crash recovery routine, and Part XV (Resource controls) covers the memory limit the OOM killer uses.
Linux for Production Sysadmins — Part LXXVIII (Containers from the Linux perspective) covers what a container actually is, which is what makes the “it does not solve durability” argument concrete.