Note on PGDATA changes for PostgreSQL 18+

[yosifkit]

Document docker-library/postgres#1259

[tianon]

IMO we should link this explicitly over to docker-library/postgres#1259 somewhere. I wonder if we should also add more explicit guidance around setting PGDATA explicitly, either to avoid this change or to opt into this change sooner?

Suggested change

	> **Important Change:** the `PGDATA` environment variable of the image was changed to be version specific in PostgreSQL 18 and above. For 18 it is `/var/lib/postgresql/18/docker`. Later versions will replace `18` with their respective major version (e.g., `/var/lib/postgresql/19/docker` for PostgreSQL `19.x`). The defined `VOLUME` was changed in 18 and above to `/var/lib/postgresql`. Mounts and volumes should be targeted at the updated location. This will allow users upgrading between PostgreSQL major releases to use the faster `--link` when running `pg_upgrade` and mounting `/var/lib/postgresql`.
	> **Important Change:** [the `PGDATA` environment variable of the image was changed to be version specific in PostgreSQL 18 and above](https://github.com/docker-library/postgres/pull/1259). For 18 it is `/var/lib/postgresql/18/docker`. Later versions will replace `18` with their respective major version (e.g., `/var/lib/postgresql/19/docker` for PostgreSQL `19.x`). The defined `VOLUME` was changed in 18 and above to `/var/lib/postgresql`. Mounts and volumes should be targeted at the updated location. This will allow users upgrading between PostgreSQL major releases to use the faster `--link` when running `pg_upgrade` and mounting `/var/lib/postgresql`.
	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).

[yosifkit]

Ready to go once we merge docker-library/postgres#1344 and docker-library/postgres#1259.

[tianon]

With docker-library/official-images#19955, we should probably re-evaluate our ordering/wording to make sure it's clear that the 18+ behavior is the default and the prior behavior is (now) the exception.

[johto]

This is very confusing. The example for older versions tells me to do this:

--env PGDATA=/var/lib/postgresql/17/docker --volume some-postgres:/var/lib/postgresql

and then literally the next paragraph tells me not to do that:

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.

Which one should I follow?

[tianon]

You're omitting from your quotes the important context for each of those lines:

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

and

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.

Granted, yes, that later note's wording could be updated to make it more clear that you shouldn't do it if you've set PGDATA as above, but I think it's a bit of a stretch to say the separation between these isn't clear.

So to be explicitly clear: if you opt into the PGDATA change, the suggested volume is sufficient and correct. If you do not, the "important note" is correct.