How to upgrade PostgreSQL 14 to 18 in Docker Compose without losing data
PostgreSQL 14 reaches end of life on November 12, 2026, and gets no more fixes after that. In Docker you cannot just change postgres:14 to postgres:18: a new major version cannot read the old data directory, and the official image moved its volume path in version 18. This guide runs a postgres:18 container next to your old one, copies every database and role across with pg_dumpall, checks the copy, then switches your app over. The old volume is never touched, so going back is one command. The commands are for Docker Compose v2 (docker compose) and the official postgres images on Docker Hub.
Why changing the image tag is not enough
Each PostgreSQL major version stores data in its own on-disk format. If you point postgres:18 at a volume created by 14, the server refuses to start. Moving data between major versions takes a dump and restore, pg_upgrade, or logical replication. For the database sizes most single-VPS apps have, a dump and restore is the simplest and the easiest to undo.
The official image also changed where data lives. From PostgreSQL 18, PGDATA is version-specific and the image's volume is the parent directory:
| Image | Mount your volume at | PGDATA inside the container |
|---|---|---|
| postgres:17 and older | /var/lib/postgresql/data | /var/lib/postgresql/data |
| postgres:18 | /var/lib/postgresql | /var/lib/postgresql/18/docker |
Mount the volume at /var/lib/postgresql for PostgreSQL 18. Keeping the old /var/lib/postgresql/data mount on an 18 container means the database files are not written where your named volume is, and you can lose them the next time the container is recreated.
Back up and record what you have
Before you change anything, take a snapshot of the server at your provider and keep a copy of the Compose file. The examples assume the database service is called db, its volume is pgdata, and your app service is <app-service>. Replace <db-user> with the value of POSTGRES_USER and <db-name> with your database name.
cp docker-compose.yml docker-compose.yml.pg14
docker compose exec db psql -U <db-user> -d postgres -c 'SELECT version();'
docker compose exec db psql -U <db-user> -d postgres -c '\l'
docker compose exec db psql -U <db-user> -d <db-name> -c '\dx'
docker compose exec db psql -U <db-user> -d <db-name> -c 'SELECT count(*) FROM <important-table>;'Write down the row counts of two or three tables that matter, so you can compare them after the restore. The \dx line lists extensions. If you use one that is not in the official image, such as PostGIS or pgvector, use that project's image built for PostgreSQL 18 instead of postgres:18 in the steps below.
Add a postgres:18 service beside the old one
Add a second service with the same credentials and a new, empty volume mounted at the new path. Leave db exactly as it is.
services:
db:
image: postgres:14
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
volumes:
- pgdata:/var/lib/postgresql/data
db18:
image: postgres:18
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
volumes:
- pgdata18:/var/lib/postgresql
volumes:
pgdata:
pgdata18:docker compose up -d db18
docker compose exec db18 pg_isready -U <db-user>Wait until pg_isready reports accepting connections. The image only creates the user and database from the environment variables when the data directory is empty, which it is for the new volume.
Stop writes and copy everything across
Stop the app so nothing changes while you copy. Then dump the old server using the PostgreSQL 18 pg_dumpall inside db18, as the PostgreSQL docs recommend using the newer version's dump tools. pg_dumpall writes every database plus the roles and their passwords, which a single-database pg_dump leaves out.
docker compose stop <app-service>
docker compose exec -T db18 sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_dumpall -h db -U "$POSTGRES_USER"' > pg14-dumpall.sql
chmod 600 pg14-dumpall.sql
ls -lh pg14-dumpall.sql
tail -n 3 pg14-dumpall.sqlThe single quotes make the variables expand inside the container, where POSTGRES_USER and POSTGRES_PASSWORD are set. The last lines of a complete dump end with PostgreSQL database cluster dump complete. If you use POSTGRES_PASSWORD_FILE instead, replace $POSTGRES_PASSWORD with $(cat "$POSTGRES_PASSWORD_FILE").
Now load the dump into PostgreSQL 18. Connections over the Unix socket inside the container do not need a password.
docker compose exec -T db18 sh -c 'psql -X -U "$POSTGRES_USER" -d postgres' < pg14-dumpall.sql 2> restore-errors.log
grep ERROR restore-errors.logExpect at most two errors: role "<db-user>" already exists, and database "<db-name>" already exists for the database the image created. Both objects were made by the image when db18 started, and the PostgreSQL docs describe the role error as harmless. Any other error, such as a missing extension, needs fixing before you switch.
The dump contains every role's password hash. Keep it readable only by you, copy it off the server along with your other backups, and delete stray copies once you are done.
Check the new database before you switch
docker compose exec db18 psql -U <db-user> -d postgres -c 'SELECT version();'
docker compose exec db18 psql -U <db-user> -d postgres -c '\l'
docker compose exec db18 psql -U <db-user> -d <db-name> -c 'SELECT count(*) FROM <important-table>;'
docker compose exec db18 sh -c 'vacuumdb -U "$POSTGRES_USER" -a -z'The row counts should match what you wrote down. vacuumdb -a -z vacuums and analyzes every database, so the planner has fresh statistics from the first query.
Next, check for passwords stored as MD5 hashes. The image uses scram-sha-256 for network connections, and a role whose password is stored as an MD5 hash cannot log in with scram-sha-256. PostgreSQL 18 also deprecates MD5 passwords. Roles created on a 14 image normally use SCRAM already, but databases that started life on an older version may not.
docker compose exec db18 psql -U <db-user> -d postgres -c "SELECT rolname FROM pg_authid WHERE rolpassword LIKE 'md5%';"If any roles are listed, set their passwords again so they are stored as SCRAM:
docker compose exec db18 psql -U <db-user> -d postgres -c "ALTER ROLE <role-name> WITH PASSWORD '<password>';"Switch the app to PostgreSQL 18
Stop both database containers. Then edit the Compose file: change db to image: postgres:18, change its volume line to pgdata18:/var/lib/postgresql, and delete the db18 service. Keep both volumes listed under volumes:.
services:
db:
image: postgres:18
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
volumes:
- pgdata18:/var/lib/postgresql
volumes:
pgdata:
pgdata18:docker compose stop db db18
docker compose up -d --remove-orphans
docker compose exec db psql -U <db-user> -d postgres -c 'SELECT version();'
docker compose logs --tail=50 <app-service>--remove-orphans removes the old db18 container. Its data stays in the pgdata18 volume, which db now uses. Your app keeps connecting to the host name db, so its connection settings do not change. Click through the parts of the app that write data before you call it done.
Never run docker compose down -v on this project. The -v flag deletes named volumes, including pgdata, which holds your PostgreSQL 14 data and is your way back.
Roll back if something is wrong
The PostgreSQL 14 volume is exactly as it was when you stopped the app. To go back, restore the old Compose file and recreate the containers:
cp docker-compose.yml.pg14 docker-compose.yml
docker compose up -d --remove-orphansAnything written to PostgreSQL 18 after the switch is not in the 14 volume, and an 18 dump is not meant to load into 14. Decide within the first hour or so, before much new data builds up. Once you are sure, and only after you have a good backup from PostgreSQL 18, remove the old volume. Find its full name with docker volume ls, because Compose prefixes it with the project name.
docker volume ls
docker volume rm <project>_pgdataSchedule backups on PostgreSQL 18
Set up the nightly dump straight away. This crontab line dumps one database, compresses it, and dates the file. In crontab, % must be escaped as \%.
0 2 * * * cd /opt/<app> && docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" -d <db-name>' | gzip > /var/backups/<db-name>-$(date +\%F).sql.gzA pg_dump file does not include roles. Save them separately with pg_dumpall --globals-only now and then, and copy both files off the server. The Docker Compose database backup guide and database backups to S3 cover rotation and offsite copies.
Prove the backup restores
Restore last night's dump into a throwaway postgres:18 container, count rows, and throw it away. This proves the file is complete and loads on the version you now run.
docker run -d --name pg-restore-test -e POSTGRES_PASSWORD=<test-password> postgres:18
sleep 10
docker exec pg-restore-test createuser -U postgres <db-user>
docker exec pg-restore-test createdb -U postgres -O <db-user> restore_test
gunzip -c /var/backups/<db-name>-<YYYY-MM-DD>.sql.gz | docker exec -i pg-restore-test psql -X -U postgres -d restore_test
docker exec pg-restore-test psql -U postgres -d restore_test -c 'SELECT count(*) FROM <important-table>;'
docker rm -f -v pg-restore-testCreating the role first lets the ownership statements in the dump succeed. docker rm -f -v removes the container and its anonymous data volume.
Frequently asked questions
- Should I upgrade to PostgreSQL 18 or wait for 19?
- PostgreSQL 18 is supported until November 14, 2030. Moving off 14 before November 12, 2026 matters more than which newer version you pick, and the same steps work for a later version when you want it.
- Can I use pg_upgrade instead of a dump?
- Yes, and it is faster for large databases. The 18 image moved its volume to /var/lib/postgresql partly so pg_upgrade can use --link between major versions. A dump and restore is simpler to run in Compose and leaves the old data untouched, which is why this guide uses it.
- Why does the restore say role already exists?
- The image creates POSTGRES_USER when the new container starts, and the dump tries to create it again. The PostgreSQL docs say this error is expected and harmless.
- Do the same steps work for 15, 16 or 17?
- Yes. Swap the version numbers. Remember that images up to 17 mount at /var/lib/postgresql/data and 18 mounts at /var/lib/postgresql.
How this was checked
Commands, limits and prices were checked against these official pages, on November 2, 2026: