PostgreSQL 18 migration

New users don’t need this guide. Run docker compose up and you’re ready.

The database was upgraded from PostgreSQL 15 to 18. This is a breaking change for existing local environments — the internal file format changed, so the old Docker volume is incompatible. If you see FATAL: database files are incompatible with server, follow the steps below.

Migration steps

Back up your data

While your v15 container is still running:

docker compose exec -T postgres pg_dumpall -c -U user > dump.sql

Remove the old volume

The internal file structure changed in v18. You must delete the old volume:

# Option A: Delete all volumes (simplest)
docker compose down -v

# Option B: Delete only the Postgres volume
docker volume rm aegra_postgres_data

Make sure you have the dump from step 1 before proceeding.

Start the database

Pull the latest changes and start only the database:

git pull origin main
docker compose up -d postgres

Restore your data

Wait a few seconds for the database to initialize, then restore:

cat dump.sql | docker compose exec -T postgres psql -U user -d postgres

Start the application

docker compose down
docker compose up -d

Troubleshooting

Container fails with 'database files are incompatible'

You didn’t remove the old volume. Run:

docker compose down -v
docker compose up -d

This removes all data and starts fresh. If you need to preserve data, follow the full migration steps above.

Restore fails with 'relation already exists'

The application started before the restore and created empty tables. Remove the volume and try again from step 2:

docker compose down -v
docker compose up -d postgres
cat dump.sql | docker compose exec -T postgres psql -U user -d postgres
docker compose down
docker compose up -d

Getting started

Core concepts

Data & storage

Configuration

Contributing

Reference

PostgreSQL 18 migration

Migration steps

Troubleshooting

​Migration steps

​Troubleshooting

Migration steps

Troubleshooting