Upgrading Postgres in Docker

This article was originally published on the Shipyard Blog

TLDR: Pull the pgautoupgrade Docker image from Docker Hub.

Do you need to upgrade your Docker PostgreSQL database from 9.5 to 11, from 12 to 15? At Shipyard, we’re always helping customers with upgrades. John Bachir from Healthie, one of our favorite customers, found this Docker image that handles upgrades automatically, and has since become a contributor to it. It goes without saying that you should have a backup of your data before proceeding, just as you would for any database-related task.

Automatically Upgrading Postgres in Docker

The pgautoupgrade Docker image automatically upgrades PostgreSQL in Docker to your specified version. You can swap the official Postgres image for this.

The image will detect your Postgres version and if it’s not current, it’ll automatically upgrade it along with your database files. It’ll then launch Postgres.

Pull it from Docker Hub:

docker pull pgautoupgrade/pgautoupgrade

View the repo’s source on GitHub.

Manually Upgrading Postgres in Docker

If you opt out of using the pgautoupgrade image, you can manually upgrade Postgres this way:

1. Perform a database dump: exec into your database container and use the pg_dump command with your Postgres credentials to get a .sql backup copy of your database. Save it to your host machine.

2. Remove the data directory: this is Postgres' data directory in your named database volume (usually the filepath is something like var/lib/postgresql/data). You can remove it by stopping your Docker database container and running the docker volume rm my_volume command.

3. Create a new database volume: initialize a new Docker volume for your database. You can run the docker volume create my_new_volume command to do this.

4. Change the image version: update the image tag on your pulled PostgreSQL image. Check out Docker Hub to get the right tag.

5. Restore your database dump: You can exec into your database container again, copy the .sql backup to that container, and import it into your new database. Check out the PostgreSQL docs for a walkthrough on restoring.