How do you upgrade Postgres to a new major version in Docker Compose?

Not by changing the image tag. Dump the old cluster with pg_dumpall, start the new major on an empty volume, restore the dump, then start the app. For postgres:18 and later the new volume goes at /var/lib/postgresql, not at /var/lib/postgresql/data where every older compose file mounts it, and that one line is where most first attempts fail. The deadline that makes this urgent: Postgres 14, still the version in Immich's compose file, gets its last fix on 12 November 2026.

Why changing the tag does not work#

PostgreSQL's documentation is plain about the cause: for major releases, "the internal data storage format is subject to change". Minor releases never change it, which is why postgres:16.14 to 16.15 is a pull and a restart. A major is not. Point a 17 server at a 14 data directory and it stops at startup with:

FATAL:  database files are incompatible with server
DETAIL:  The data directory was initialized by PostgreSQL version 14, which is not compatible with this version 17.11.

The official image for 18 fails differently, and earlier. Its PGDATA moved to /var/lib/postgresql/18/docker and its VOLUME to /var/lib/postgresql. If the 18 entrypoint finds an empty PGDATA but a database at /var/lib/postgresql/data, it refuses to initialise and prints Error: in 18+, these Docker images are configured to store database data in a format which is compatible with "pg_ctlcluster", followed by the explanation that this "is usually the result of upgrading the Docker image without upgrading the underlying database". It does the same if anything at all is mounted at /var/lib/postgresql/data, even an empty volume.

Both failures are safe. The data is untouched; put the old tag back and the stack starts. The confusion is that most compose files people copied were written before 18, so the obvious edit, changing 16 to 18, hits the second error and looks like a broken image.

Which apps are on which major#

The version you must leave and the mount path you have come from the compose file each project tells you to start from. Read on 11 October 2026:

And the dates that decide how long each major is safe, from the PostgreSQL project's versioning page:

End of life does not stop a server. It means one final minor release and then nothing. The pressure comes from the apps. Synapse's policy is that when a Postgres version reaches end of life it "will withdraw support for that version in future releases". Mattermost's published schedule moves the minimum to 15 at v12.0, dated 14 October 2026, and its policy says customers "will have 9 months to plan, test, and upgrade" before each new minimum. If you are on 14 and run Mattermost's feature releases, you are already late.

Dump and restore, or pg_upgrade?#

PostgreSQL documents three ways across a major: dump and restore with pg_dumpall, an in-place migration with pg_upgrade, and logical replication. For a self-hosted app the choice is between the first two.

Dump and restore is the one to use unless your database is too big to sit offline while it reloads. It works across any number of majors, it does not care about checksums or extensions beyond having them installed, and the old volume is never written to, so rolling back is putting the old tag back. It is also the procedure authentik documents for its own upgrades.

pg_upgrade is faster, and with --link it barely copies anything. It needs both versions' binaries in one place, which the official images do not provide, and it is strict: the documentation warns that in link mode "you will not be able to access your old cluster once you start the new cluster". It is the right tool when the database is too large to reload in your maintenance window. For most home databases, its speed is not worth the extra ways it can fail.

The upgrade, step by step#

This assumes a compose service called db, a superuser called app, and an app service called server. Replace the names with yours; they are in your compose file and .env.

1. Record what is running. Ask the server, not the file:

docker compose exec db psql -U app -d postgres -Atc 'SHOW server_version' -c 'SHOW data_checksums'

2. Stop the app, leave the database up, so nothing writes during the dump:

docker compose stop server

3. Dump the whole cluster. pg_dumpall includes roles, which pg_dump does not; Backing up a running database covers the difference.

docker compose exec -T db pg_dumpall -U app > pg-$(date +%F).sql
grep -c 'cluster dump complete' pg-$(date +%F).sql   # 1 means the dump finished

PostgreSQL recommends dumping with the newer version's pg_dumpall where you can, "to take advantage of enhancements". Running the old container's own tool also works, and it is what authentik's guide does.

4. Bring the stack down and change two lines. Do not reuse the old volume. A new one leaves the old data exactly as it was:

services:
  db:
    image: postgres:18          # was postgres:16-alpine
    volumes:
      - pgdata18:/var/lib/postgresql   # was pgdata:/var/lib/postgresql/data
volumes:
  pgdata:       # keep it until you are sure
  pgdata18:

5. Start only the database, then restore:

docker compose down
docker compose up -d db
docker compose exec -T db psql -U app -d postgres < pg-$(date +%F).sql
docker compose exec db vacuumdb -U app --all --analyze-only

Expect two harmless errors near the top, role "app" already exists and database "app" already exists, because the image created both from POSTGRES_USER and POSTGRES_DB on first start. Any other error is not harmless; stop and read it.

6. Start the app and use it. docker compose up -d, log in, open something old and something new. Leave pgdata in place for a week, and keep the dump. That is your rollback: the old tag, the old volume name, up -d.

The checksum trap, if you use pg_upgrade anyway#

If the database is large enough that dump and restore is not an option, the tianon/postgres-upgrade images package both versions' binaries as tags such as 16-to-18, and pgautoupgrade wraps the same idea into an image that upgrades whatever it finds at startup. Both run into one change in Postgres 18 that older guides predate.

Postgres 18's initdb enables data checksums by default. Every earlier version defaulted to off, so a cluster created by postgres:16 or postgres:14 with default settings has none. pg_upgrade requires both clusters to match, and its source has no way round it:

old cluster does not use data checksums but the new one does

Run SHOW data_checksums on the old server first. If it says off, the new cluster has to be created with --no-data-checksums; tianon's image initialises the new cluster with whatever is in POSTGRES_INITDB_ARGS, so set it to that. If it says on, as it will for Immich's database, the default matches. Two more things change at 18: pg_upgrade now carries most optimizer statistics across, and the documentation's post-upgrade step is vacuumdb --all --analyze-in-stages --missing-stats-only followed by vacuumdb --all --analyze-only.

Treat both tools as what they say they are. tianon's README calls itself a proof of concept: "don't expect it to work as-is". pgautoupgrade upgrades in place with --link, removes the old cluster data, and opens its README with "Backup your data!". Take the dump from step 3 either way.

Immich: leave it on Immich's image#

Immich's database is not plain Postgres. It needs the VectorChord extension preloaded, which is why it runs ghcr.io/immich-app/postgres rather than the official image, and why sharing its server is a bad idea. Immich publishes that image for 15, 16, 17 and 18, but the 18 tags carry VectorChord 0.5.3 or 1.1.1, not the 0.4.3 its compose file pins, so moving Immich to 18 changes the extension version in the same step. Immich's upgrade documentation gives no procedure for a Postgres major.

So the honest recommendation is to wait for Immich to move its compose file, and to be clear about the cost. From 12 November its database runs an unsupported Postgres. The reference compose file publishes no port for it, so it is reachable only from Immich's own containers, which makes that a smaller risk than an unpatched service on your network. When you do move it, use Immich's own backup and restore procedure, which includes a sed line that rewrites the dump's search_path, rather than the generic one above.

When this answer stops applying#

• Not the official image. Bitnami, Immich's image and others set their own paths and users. The 18 path change and the entrypoint error are specific to the official postgres image.
• A shared server. One pg_dumpall moves every app's database at once, so every app has to support the target major. The per-app version table is the check.
• Databases too large to reload in your maintenance window. Then pg_upgrade is the right tool, with the checksum setting matched and a tested backup.
• The table moves. Every row reflects the compose files as read on 11 October 2026.

What to do next#

Run the version check from step 1 against every Postgres container you have, and list any on 14. Do those first, then anything feeding an app with a published minimum, such as Mattermost or Synapse. Before you start, make sure last night's dump actually restores: Backups that actually restore has the rehearsal, and Backup planner schedules it. Then pin the new major in the compose file, never latest, for the reasons in An update strategy that does not lose data.