Inconsistencies in docker-compose

[n-bux]

I came across some inconsistencies in the provided docker-compose:

1. Issue #7287 is not reflected in/on

• /docker-compose.yml and README.md on develop-Branch
• /doc/docker.*#ready-to-use-docker-compose (e.g. here on all (?) branches

2. postgresql-Volume

• in /docker-compose.yml and the example of it in /README.md there is an inconsistency, which in some circumstances might lead to errors:

It instructs the postgres-Image to use
PGDATA: /var/lib/postgresql/data/pgdata

but doesn't include this subdir in the volume.

LLM said about this:

Volume:

- postgres_data:/var/lib/postgresql/data

This tells Docker:

• Persist only /var/lib/postgresql/data
• But PostgreSQL will store its database cluster files inside /var/lib/postgresql/data/pgdata

Because pgdata/ is a subdirectory, and the parent (/var/lib/postgresql/data) is the mount point, the files will technically still be inside the mounted volume. So PostgreSQL will not lose data as long as the subdirectory exists.

BUT:

The real problem

PostgreSQL’s entrypoint script in the official Docker image behaves differently depending on whether the PGDATA directory is empty at startup.

If the parent directory /var/lib/postgresql/data contains anything at all (e.g., leftover files from previous runs or permissions mismatches), initialization can fail or behave unpredictably.

Mounting the parent while using a custom PGDATA directory is explicitly discouraged by Postgres maintainers.

Why the docs version is safer

The docs align the PGDATA setting with the mount point:

PGDATA: /var/lib/postgresql/data/pgdata
volumes:
  - postgres_data:/var/lib/postgresql/data/pgdata

This ensures:

• Docker volume exactly matches the PGDATA directory
• No parent directory interference
• No entrypoint surprises
• Clean upgrades and restores