Documentation is confusing in relation to setting PGDATA for older versions of PostgreSQL

[SpokeyWheeler]

The documentation says:

Users who wish to opt-in to this change on older releases can do so by setting PGDATA explicitly (--env PGDATA=/var/lib/postgresql/17/docker --volume some-postgres:/var/lib/postgresql ). To migrate pre-existing data, adjust the volume's folder structure appropriately first (moving all database files into a PG_MAJOR/docker subdirectory).

It then goes on to say:

Important Note: (for PostgreSQL 17 and below) Mount the data volume at /var/lib/postgresql/data and not at /var/lib/postgresql because mounts at the latter path WILL NOT PERSIST database data when the container is re-created. The Dockerfile that builds the image declares a volume at /var/lib/postgresql/data and if no data volume is mounted at that path then the container runtime will automatically create an anonymous volume that is not reused across container re-creations. Data will be written to the anonymous volume rather than your intended data volume and won't persist when the container is deleted and re-created.

Surely give what the second paragraph says, the first paragraph should read:

Users who wish to opt-in to this change on older releases can do so by setting PGDATA explicitly (--env PGDATA=/var/lib/postgresql/17/docker --volume some-postgres:/var/lib/postgresql/data ). To migrate pre-existing data, adjust the volume's folder structure appropriately first (moving all database files into a PG_MAJOR/docker subdirectory).

[tianon]

In PostgreSQL 17, the volume and PGDATA are both on /var/lib/postgresql/data. In 18+, PGDATA gets set to /var/lib/postgresql/PG_MAJOR/docker and the volume path goes down a level to /var/lib/postgresql, better matching a "standard" installation (see docker-library/postgres#1259).

The point the documentation is trying to make is that if you want to "upgrade" to that standard layout earlier than 18+, you can do so by adjusting PGDATA and moving your persistent volume to the new path, so the documentation is correct (even if the wording could probably be improved).