PostgreSQL Docker Upgrade: Major Version Migration

This guide explains how to safely upgrade a PostgreSQL Docker container from one major version to another (e.g., version 12 to 16) using a dump and restore method. This is the recommended approach in Docker environments.

⚠️ Important

PostgreSQL data directories are not compatible across major versions. You cannot just point a newer version to the old data volume. You must export and re-import your data.

💾 Step 1: Start a temporary container with your current PostgreSQL version

Replace <old-version> with your current PostgreSQL version (e.g., 12).

docker run --rm -d \
  --name pg-old \
  -v pgdata:/var/lib/postgresql/data \
  postgres:<old-version>

This container mounts your old data volume and runs the matching PostgreSQL version.

⬇️ Step 2: Dump all databases

docker exec pg-old pg_dumpall -U postgres > backup.sql

Stop the old container:

docker stop pg-old

💥 Step 3: Remove the old data volume

docker volume rm pgdata

⚠️ This will permanently delete your old PostgreSQL data files. Make sure you have a successful backup (backup.sql) before running this!

📦 Step 4: Start a new container with your target PostgreSQL version

Replace <new-version> with the version you want to upgrade to (e.g., 16).

docker run --rm -d \
  --name pg-new \
  -v pgdata:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=secret \
  postgres:<new-version>

This creates a clean PostgreSQL instance with a fresh data directory.

⬆️ Step 5: Restore your data

cat backup.sql | docker exec -i pg-new psql -U postgres

This restores all roles, databases, and data into your new PostgreSQL instance.

✅ Done!

You now have the target PostgreSQL version running with your old data successfully restored.

📝 Tips

Always test this procedure in a staging environment before running it in production.
You can automate this with Ansible or a custom script.
For large databases, consider using pg_dump per database and pg_restore with parallel jobs.

2.3 KiB Raw Blame History