Step-by-step guide for upgrading PostgreSQL Docker containers

Recently I upgraded a couple of apps which were running an outdated PostgreSQL database with Docker containers (I use Docker Compose to manage them), and had a hard time finding a good guide on how to do it. Most were too complicated, outdated, or just unnecessarily complex for me.

The process should be really simple, and I had done it before, but I believe in the power of checklists, and somehow, I didn't have one handy.

So I decided to write one, and share it with you here!

NOTE: This guide assumes the easiest way to upgrade the PostgreSQL is to export the database, start a new container, and import the database into it. This is the easiest way, but it's not the only way. You can find other, more complicated and complex ways to do it officially, but if your database isn't over ~50GB, this is the easiest and simplest way in my opinion.

Step 1: Dump the database

First, we need a dump of the database. We'll need it to seed the new container. We don't need to stop the container for this, as we'll be using pg_dump.

docker exec -it <container-name> pg_dump -U <username> <database-name> > db_backup.sql

Step 2: Stop the container

Now we need to stop the container, so we can upgrade the PostgreSQL version.

docker compose stop <container-name>

Step 3: Upgrade the PostgreSQL version

Now we need to upgrade the PostgreSQL version. Assuming you were, for example, running PostgreSQL 15 and you want to upgrade to 17, you would make the following changes to the docker-compose.yml file:

+  image: postgres:17
-  image: postgres:15

Step 4: Start the container

Now we need to start the new container, running the new PostgreSQL version.

docker compose up -d <container-name>

Step 5: Import the database

Now we need to import the database into the new container.

cat db_backup.sql | docker exec -i <container-name> psql -U <username> <database-name>

That's it!

I hope this helps you.

Thank you so much for being here. I really appreciate you!