PostgreSQL 19 came out on November 19. I maintain a small tool that runs Postgres in Docker, so I spent the last few days moving it to 19. Most of it was boring, which is good. Some of it wasn't.
Everything below was run against the official postgres:17, postgres:18 and postgres:19 images. The output is from my terminal, with timestamps and noise trimmed.
1. If you skipped 18: the data directory moved
This changed in 18, but if you're going from 17 straight to 19, it's the first thing that will stop you.
$ docker image inspect postgres:17 postgres:18 postgres:19 ...
postgres:17 PGDATA=/var/lib/postgresql/data VOLUME /var/lib/postgresql/data
postgres:18 PGDATA=/var/lib/postgresql/18/docker VOLUME /var/lib/postgresql
postgres:19 PGDATA=/var/lib/postgresql/19/docker VOLUME /var/lib/postgresql
Your old compose file almost certainly has - pgdata:/var/lib/postgresql/data. With 19 the container won't start:
Error: in 18+, these Docker images are configured to store database data in a
format which is compatible with "pg_ctlcluster" (specifically, using
major-version-specific directory names).
...
Counter to that, there appears to be PostgreSQL data in:
/var/lib/postgresql/data (unused mount/volume)
I got that with a brand new, empty volume too. The entrypoint refuses any mount at the old path, not just one with data in it.
For a new setup, change the mount path:
services:
db:
image: postgres:19
volumes:
- pgdata:/var/lib/postgresql # not /var/lib/postgresql/data
For an existing volume, changing the path isn't enough: the data inside is still 17's and 19 can't read it. You need a dump/restore or pg_upgrade (section 4). The new layout exists so both majors can live under one mount (/var/lib/postgresql/17/docker, /var/lib/postgresql/19/docker) and pg_upgrade --link works without crossing a mount boundary.
2. io_workers is gone, and the server won't start with it
18 added async I/O, with io_method = worker by default and io_workers to size the pool. If you tuned 18, you might have set it. 19 removed it and replaced it with io_min_workers (default 2), io_max_workers (default 8), io_worker_idle_timeout and io_worker_launch_interval. The pool scales itself now.
An unknown setting is FATAL at startup, and the official image passes your -c flags to the temporary server it starts during init. So on a fresh volume, initdb succeeds and then:
$ docker run --rm -e POSTGRES_PASSWORD=x -v pgtest:/var/lib/postgresql postgres:19 -c io_workers=4
...
Success. You can now start the database server using:
pg_ctl -D /var/lib/postgresql/19/docker -l logfile start
2026-11-22 04:38:04.631 GMT [48] FATAL: unrecognized configuration parameter "io_workers"
In compose with restart: unless-stopped, that's a restart loop.
On a fresh install this is harmless. What got my attention is when the error shows up during an upgrade: on the new major's first start, after the old cluster has been dumped, moved or deleted. My tool's major upgrade did exactly that: dump, remove the old volume, start the new cluster with the instance's settings, restore. With io_workers in the settings, the new cluster wouldn't start and the only way back was the pre-upgrade backup. It worked as designed, but it's not a fun place to end up.
Check your settings against the new binary first
postgres -C <name> prints one setting and exits without starting a server. It still parses everything you pass, so it works as a validator. You don't need a data directory with a cluster in it:
docker run --rm --network none --user 65534 --entrypoint postgres postgres:19 \
-D /tmp -c config_file=/dev/null \
-c shared_buffers=1GB -c io_workers=4 \
-C server_version_num
-
--user 65534: postgres refuses to run as root. -
--entrypoint postgres: skipdocker-entrypoint.sh, which would try to init and start a server. -
-D /tmp: it wants a directory that exists. It only looks there forpostgresql.auto.conf. -
--network none: it doesn't need any.
Same flags against 18 and 19:
== 18
LOG: skipping missing configuration file "/tmp/postgresql.auto.conf"
180007
== 19
FATAL: unrecognized configuration parameter "io_workers"
If you use a postgresql.conf file instead of -c flags, mount it and point config_file at it. You even get the line number:
docker run --rm --network none --user 65534 \
-v "$PWD/postgresql.conf:/etc/postgresql/postgresql.conf:ro" \
--entrypoint postgres postgres:19 \
-D /tmp -c config_file=/etc/postgresql/postgresql.conf -C server_version_num
LOG: unrecognized configuration parameter "io_workers" in file "/etc/postgresql/postgresql.conf" line 2
FATAL: configuration file "/etc/postgresql/postgresql.conf" contains errors
It also catches bad values (wrong units, out of range), not just unknown names. It won't catch a shared_preload_libraries entry the image doesn't have, rules that involve two settings at once, or not having enough shared memory. Those still only show up on a real start.
Settings you applied with ALTER SYSTEM live in postgresql.auto.conf in the data directory. pg_upgrade doesn't carry them over, but if you copy that file across by hand, check it too.
3. Defaults that changed
These don't stop anything from starting. They just behave differently.
max_locks_per_transaction went from 64 to 128, and the number means something different. The lock table is allocated differently in 19. The release notes say settings "must now be doubled to match their capacity in previous releases". If you never set it, you're fine, since the default was doubled for you. If you raised it to 256 for a schema with thousands of partitions, set 512 on 19 or you'll get roughly half the capacity you had.
18 max_locks_per_transaction = 64
19 max_locks_per_transaction = 128
JIT is off by default. The release notes say the costing that decided when to JIT turned out to be unreliable. For OLTP this is probably a small win. If you run big analytical queries and they got slower after the upgrade, try jit = on first.
18 jit = on
19 jit = off
MD5 password logins now log a warning. MD5 was deprecated in 18. In 19 every successful MD5 login warns (md5_password_warnings = off silences it). The real fix is to move those roles to SCRAM. Find them:
SELECT rolname FROM pg_authid WHERE rolpassword LIKE 'md5%';
then reset their passwords while password_encryption = scram-sha-256 (the default since 14). You'll usually find them in old images and old pg_hba.conf files.
standard_conforming_strings is always on. A dump made by an older pg_dump with it off won't load correctly into 19.
4. Upgrading a compose setup: dump with 19's tools
When you move data across majors, use the new version's pg_dump/pg_dumpall. That was always the advice, and with the change above it's now required. In Docker it's easy, because you can run 19's client against the old server without installing anything:
# old server: postgres:17 container "db-old", new: postgres:19 container "db-new"
# both on the same docker network "pgnet"
docker run --rm --network pgnet -e PGPASSWORD=... postgres:19 \
pg_dumpall -h db-old -U postgres \
| docker exec -i db-new psql -U postgres
I ran this 17 -> 19 with a test database and got all rows back on PostgreSQL 19.0 (Debian 19.0-1.pgdg13+1). Expect a harmless role "postgres" already exists error. For anything big, use pg_dump -Fc per database and pg_restore -j instead of one big SQL stream.
If you'd rather use pg_upgrade, 19 refuses to upgrade a cluster that has any of these, so check before you schedule downtime:
-
btree_gistindexes oninet/cidrcolumns (those opclasses could skip rows; 19 switched the defaults to the core GiST ones) - database, role or tablespace names containing CR or LF
- the
MULE_INTERNALencoding (removed)
After pg_upgrade, the notes also recommend reindexing full-text-search and pg_trgm indexes on ICU/builtin-locale databases, and anything that uses the fuzzystrmatch functions, since their character handling changed.
Before you bump the tag
- Volume mounted at
/var/lib/postgresql, not/var/lib/postgresql/data. - No
io_workersanywhere:-cflags,postgresql.conf,postgresql.auto.conf. Run thepostgres -Ccheck above againstpostgres:19with your real settings, before you touch the old data. - If you set
max_locks_per_transaction, double it. - Decide whether you want JIT back.
- Move MD5 roles to SCRAM.
- Dump with 19's
pg_dump, not the old container's.
The tool I mentioned is oddk. It runs Postgres containers on a single Linux host and handles snapshots to S3, alerts, and major upgrades. As of v0.1.97 it supports 19, and its major upgrade runs the postgres -C check above before it touches anything. MIT licensed. If you self-host Postgres on one box and don't want to write the cron jobs yourself, take a look.
Top comments (2)
The data directory move is the one that catches people, and your point that even a brand new empty volume trips the entrypoint check is a detail I hadn't seen spelled out. We run Postgres in compose for local dev on our Django projects, so the advice to mount /var/lib/postgresql rather than the old data path is very practical. For existing volumes, did you find pg_upgrade --link noticeably faster than dump/restore on your test data, or was the difference small at that size?
Catching io_workers with postgres -C before the container starts beats finding it in a FATAL after the image is already up.