From a5b12488e6dbb00a138da0c50bdc39f6ef0140c9 Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Thu, 25 Sep 2025 16:42:27 -0700 Subject: [PATCH] Update PostgreSQL documentation now that 18 is GA This adjusts some examples to use `/var/lib/postgresql` as appropriate, and dials in some other language to be more focused on the 18+ reality. --- postgres/content.md | 29 ++++++++--------------------- 1 file changed, 8 insertions(+), 21 deletions(-) diff --git a/postgres/content.md b/postgres/content.md index 87cd0c59305b..9e2e30f89bb8 100644 --- a/postgres/content.md +++ b/postgres/content.md @@ -102,20 +102,7 @@ Users who wish to opt-in to this change on older releases can do so by setting ` > **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](https://docs.docker.com/engine/storage/#volumes) 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. -This optional variable can be used to define another location - like a subdirectory - for the database files. The default is `/var/lib/postgresql/data`. If the data volume you're using is a filesystem mountpoint (like with GCE persistent disks), or remote folder that cannot be chowned to the `postgres` user (like some NFS mounts), or contains folders/files (e.g. `lost+found`), Postgres `initdb` requires a subdirectory to be created within the mountpoint to contain the data. - -For example: - -```console -$ docker run -d \ - --name some-postgres \ - -e POSTGRES_PASSWORD=mysecretpassword \ - -e PGDATA=/var/lib/postgresql/data/pgdata \ - -v /custom/mount:/var/lib/postgresql/data \ - %%IMAGE%% -``` - -This is an environment variable that is not Docker specific. Because the variable is used by the `postgres` server binary (see the [PostgreSQL docs](https://www.postgresql.org/docs/14/app-postgres.html#id-1.9.5.14.7)), the entrypoint script takes it into account. +This (`PGDATA`) is an environment variable that is not Docker specific. Because the variable is used by the `postgres` server binary (see the [PostgreSQL docs](https://www.postgresql.org/docs/14/app-postgres.html#id-1.9.5.14.7)), the entrypoint script takes it into account. ## Docker Secrets @@ -204,7 +191,7 @@ When using the Alpine variants, any postgres extension not listed in [postgres-c As of [docker-library/postgres#253](https://github.com/docker-library/postgres/pull/253), this image supports running as a (mostly) arbitrary user via `--user` on `docker run`. As of [docker-library/postgres#1018](https://github.com/docker-library/postgres/pull/1018), this is also the case for the Alpine variants. -The main caveat to note is that `postgres` doesn't care what UID it runs as (as long as the owner of `/var/lib/postgresql/data` matches), but `initdb` *does* care (and needs the user to exist in `/etc/passwd`): +The main caveat to note is that `postgres` doesn't care what UID it runs as (as long as the owner of `PGDATA` matches), but `initdb` *does* care (and needs the user to exist in `/etc/passwd`): ```console $ docker run -it --rm --user www-data -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%% @@ -230,13 +217,13 @@ The three easiest ways to get around this: 3. initialize the target directory separately from the final runtime (with a `chown` in between): ```console - $ docker volume create pgdata - $ docker run -it --rm -v pgdata:/var/lib/postgresql/data -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%% + $ docker volume create pg + $ docker run -it --rm -v pg:/var/lib/postgresql -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%% The files belonging to this database system will be owned by user "postgres". ... ( once it's finished initializing successfully and is waiting for connections, stop it ) - $ docker run -it --rm -v pgdata:/var/lib/postgresql/data bash chown -R 1000:1000 /var/lib/postgresql/data - $ docker run -it --rm --user 1000:1000 -v pgdata:/var/lib/postgresql/data %%IMAGE%% + $ docker run -it --rm -v pg:/var/lib/postgresql bash chown -R 1000:1000 /var/lib/postgresql + $ docker run -it --rm --user 1000:1000 -v pg:/var/lib/postgresql %%IMAGE%% LOG: database system was shut down at 2017-01-20 00:03:23 UTC LOG: MultiXact member wraparound protections are now enabled LOG: autovacuum launcher started @@ -262,7 +249,7 @@ The Docker documentation is a good starting point for understanding the differen 2. Start your `%%IMAGE%%` container like this: ```console - $ docker run --name some-%%REPO%% -v /my/own/datadir:/var/lib/postgresql/data -e POSTGRES_PASSWORD=mysecretpassword -d %%IMAGE%%:tag + $ docker run --name some-%%REPO%% -v /my/own/datadir:/var/lib/postgresql -e POSTGRES_PASSWORD=mysecretpassword -d %%IMAGE%%:tag ``` -The `-v /my/own/datadir:/var/lib/postgresql/data` part of the command mounts the `/my/own/datadir` directory from the underlying host system as `/var/lib/postgresql/data` inside the container, where PostgreSQL by default will write its data files. +The `-v /my/own/datadir:/var/lib/postgresql` part of the command mounts the `/my/own/datadir` directory from the underlying host system as `/var/lib/postgresql` inside the container, where PostgreSQL by default will write its data files.