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.

[erjoalgo]

I ran into this error and found the note rather long and not very helpful in answer the question: how do I fix this? I appreciate the links to all the context and history but I think the first thing should be concise concrete steps on how to fix this, e.g.

To work around this breaking change and get your postgres DB back up and running, you can:

- either set  the PGDATA environment variable inside your container: `PGDATA=/var/lib/postgresql/data`
- change your pgdata mountpoint from `/var/lib/postgresql/data` to X...