PostgreSQL 18 migration

Migrate your local PostgreSQL data from version 15 to 18.

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

1. Back up your data

   While your v15 container is still running:

   docker compose exec -T postgres pg_dumpall -c -U user > dump.sql
   
2. 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.

3. Start the database

   Pull the latest changes and start only the database:

   git pull origin main
   docker compose up -d postgres
   
4. 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
   
5. 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