PostgreSQL in a container image · PostgreSQL

Every lab in this course runs PostgreSQL in a container, because a disposable database you can destroy and recreate is exactly what practice requires. That convenience comes with a set of behaviours that differ from a package installation in ways worth knowing explicitly, particularly if a containerised database ever becomes something other than a lab.

This lesson is about the image’s behaviour. Whether a production database belongs in a container is a separate question, and Part XVIII answers it properly.

What the entrypoint does, and when it does nothing

The image’s entrypoint script runs before PostgreSQL starts, and its first decision is the one that surprises people: it checks whether the data directory is already initialised, and if it is, it skips almost everything.

On a genuinely empty data directory it runs initdb, applies POSTGRES_PASSWORD, POSTGRES_USER and POSTGRES_DB, starts a temporary server on the Unix socket only, runs any scripts found in /docker-entrypoint-initdb.d/, shuts that temporary server down, and then starts the real one.

On a data directory that already contains a cluster, it does none of that. It starts the server.

Changing POSTGRES_PASSWORD on an existing volume and expecting it to apply

This is the single most common misunderstanding of the image, and it fails in both directions.

An operator changes POSTGRES_PASSWORD in a compose file and recreates the container, expecting the superuser password to rotate. The data directory already exists on the volume, so the entrypoint skips initialisation entirely and the old password remains in force. Nothing reports this. The change appears to have been applied because the container started successfully.

The mirror-image failure is worse. Somebody concludes the volume is the problem and removes it. The entrypoint now finds an empty directory, runs initdb, and starts a brand-new empty cluster with the new password. Every table is gone, and the container is healthy, which is exactly what makes it plausible that the fix worked.

To change the password on an existing cluster, change it in the database with ALTER ROLE postgres PASSWORD .... The environment variable is an initialisation input, not a desired-state declaration.

The same applies to /docker-entrypoint-initdb.d/ scripts: they run once, on first initialisation, and adding one later to an existing volume does nothing at all.

The image is invisible to its own cluster tooling

The official image is built from the Debian packages, so the Debian cluster wrappers are installed. It does not use them.

Read-only / Safepg_lsclusters inside the running official image— A header row and nothing else, while PostgreSQL serves happily on 5432. Captured from a live container.

$ docker exec rbpg-multi pg_lsclusters

Ver Cluster Port Status Owner Data directory Log file

The wrappers enumerate clusters by reading /etc/postgresql/<version>/<name>/, and the image keeps its configuration inside the data directory in the Red Hat style instead. There is nothing registered for them to find.

Two consequences. First, any automation that discovers PostgreSQL by running pg_lsclusters reports zero clusters against a container, and zero is indistinguishable from “not installed” in most such scripts. Second, pg_ctlcluster, pg_createcluster and pg_upgradecluster are all present and none of them will manage the running cluster, so a runbook step that uses them silently addresses nothing.

Creating a second cluster inside the image with pg_createcluster does work and does register, which produces a container where one cluster is visible to the tooling and the one actually serving traffic is not.

PID 1, and who chooses your shutdown mode

In the image, PostgreSQL is PID 1. There is no systemd, no init system, and no supervisor. The container runtime signals the postmaster directly, and which signal it sends decides the shutdown mode from the previous lesson.

docker stop sends SIGTERM, waits for a grace period — ten seconds by default — and then sends SIGKILL.

SIGTERM to a PostgreSQL postmaster is smart shutdown: refuse new connections and wait, indefinitely, for existing clients to disconnect voluntarily. On a container with an application connection pool attached, they will not.

So the default sequence is: request the slowest possible shutdown, wait ten seconds, then kill it outright. The result is a crash recovery on the next start, every time, and nobody chose it.

Set the stop signal to SIGINT and the grace period to something realistic

The fix is two settings, and it is worth applying to every containerised PostgreSQL including lab ones, because it makes the behaviour predictable.

docker run -d --name pg \
  --stop-signal=SIGINT \
  --stop-timeout=120 \
  -e POSTGRES_PASSWORD=lab-password-not-a-real-secret \
  postgres:18

SIGINT is fast shutdown: disconnect clients, roll back their open transactions, write the shutdown checkpoint, exit. --stop-timeout raises the grace period above the ten-second default so the checkpoint can actually finish.

In Compose the equivalents are stop_signal: SIGINT and stop_grace_period: 120s. In Kubernetes it is terminationGracePeriodSeconds combined with the image’s STOPSIGNAL, and Part XVIII covers the cluster case.

Verify it worked the way the previous lesson described: after a stop, pg_controldata should read shut down, and the next start should contain no recovery message.

Volumes are the data directory

# A named volume: survives container removal, which is the point.
docker run -d --name pg -v pgdata:/var/lib/postgresql/data postgres:18

# A bind mount: the data directory is a host path you can see
docker run -d --name pg -v /srv/pgdata:/var/lib/postgresql/data postgres:18

# Nothing: an anonymous volume you will lose track of and eventually prune
docker run -d --name pg postgres:18

The third form is what every quick example uses, including the labs in this course, and it is correct for a disposable database. An anonymous volume persists after docker rm, but nothing names it, so it is invisible in practice and docker volume prune removes it. For a database holding anything you would miss, that is the wrong default.

Note also that the PostgreSQL 18 image sets PGDATA to a subdirectory, /var/lib/postgresql/18/docker, rather than to the mount point itself. The entrypoint handles this, but a bind mount whose contents you are inspecting from the host will have the cluster one level down from where you expect.

Why the entrypoint starts a temporary server before the real one

The initialisation sequence looks convoluted and each step exists for a reason worth knowing, because it explains a behaviour you will observe.

initdb creates a cluster but cannot execute SQL. Setting a password, creating POSTGRES_DB and running the scripts in /docker-entrypoint-initdb.d/ all require a running server. So the entrypoint starts one.

The critical detail is how it starts it. The temporary server listens on the Unix socket only, with listen_addresses empty, so it is unreachable from the network for the entire initialisation window. This matters: during that window the superuser password may not be set yet, and the scripts may be creating roles and loading data. Exposing that state to the network, even briefly, would be a real window of vulnerability on a published port.

When initialisation finishes, the temporary server is shut down cleanly, and only then is the real server started with the configured listen_addresses.

This explains the behaviour every lab in this course works around: for several seconds after the container reports as running, connections from outside fail, because the server accepting connections on the socket is deliberately not accepting them from anywhere else. It is also why pg_isready polled through docker exec succeeds slightly before a TCP connection from the host does — they are asking different servers at that moment.

Waiting on pg_isready rather than on a fixed sleep is the correct readiness test for the same reason.

What a container solves, and what it does not

Solved. Reproducible binaries and version pinning. Fast disposal and recreation. Isolation of the software from the host’s package management. Trivially running several versions side by side, which makes upgrade rehearsal genuinely easy.

Not solved. Durability, which is entirely a property of the volume and the storage beneath it. Backup, which is exactly as much work as before. High availability, which needs everything Part XV describes and gains nothing from the packaging. Connection management, capacity planning, vacuum behaviour, replication — the whole remainder of this course is unchanged.

The failure mode to name explicitly is the assumption that because the container can be recreated in seconds, the database can be. Recreating the container gives you a running PostgreSQL. It gives you your data only if the volume survived, and it gives you a correct database only if the volume was not the thing that failed.

Production discipline

Treat POSTGRES_PASSWORD as an initialisation input, not desired state. Rotate credentials with ALTER ROLE; the variable is ignored on every start after the first.
Never delete a volume to make an environment variable apply. That is the action that turns a configuration confusion into data loss, and the container comes back healthy afterwards.
Set --stop-signal=SIGINT and a realistic --stop-timeout. The default combination requests a smart shutdown that cannot complete and then kills it, producing crash recovery on every stop.
Use named volumes for anything you would miss. Anonymous volumes survive docker rm and are removed by docker volume prune, which is a routine command.
Do not discover containerised PostgreSQL with pg_lsclusters. It reports nothing, and nothing is indistinguishable from absent.

Cross-course references

Docker & Containers — Part VIII (Storage) covers volume lifetime and bind-mount behaviour, and Part VI (Container lifecycle) covers stop signals and grace periods in detail.
Kubernetes for Production Sysadmins — Part LIV (Stateful workloads) and Part X (Termination) cover the cluster-scheduler equivalents of everything in this lesson.
Secrets, PKI & Certificate Management — Part XIV (Platform integration) covers why a password in an environment variable is visible in more places than expected.