pgautoupgrade/pgautoupgrade repository overview

This is a PostgreSQL Docker container (based on postgres:17-alpine) that automatically upgrades your database.

When it starts, it checks if your database files are for an older version (from PostgreSQL 9.5 onwards), and upgrades them (if needed), then starts the database server.

If the database files don't need upgrading when it starts, then it skips the upgrade process and just starts PostgreSQL.

The upgrade process uses the pg_upgrade utility behind the scenes, with the --link option enabled. This does an in-place upgrade for the quickest possible upgrade times.

⁠WARNING! Backup your data first!

This Docker container does an in-place upgrade of the database data, so if something goes wrong you are expected to already have backups you can restore from.

⁠Purpose

It's been developed mainly because the Redash project was stuck on an old, unsupported version of PostgreSQL (9.5) for years, and we didn't want to break existing user installations by changing the version of PostgreSQL in our supplied docker-compose.yml file(s).

Using this PostgreSQL container instead, people shouldn't have to worry about PostgreSQL upgrade problems ever again.

⁠How to use this container

To always use the latest version of PostgreSQL, use the tag latest:

pgautoupgrade/pgautoupgrade:latest

If you instead want to run a specific version of PostgreSQL then pick a matching tag. For example, to use PostgreSQL 17 you can use:

pgautoupgrade/pgautoupgrade:17-alpine

⁠Debian vs Alpine based images

The default official Docker PostgreSQL image is Debian Linux based, and upgrading from that to one of our Alpine Linux based images doesn't always work out well.

To solve that problem, we have Debian based images (17-bookworm and 16-bookworm) available now as well.

To use either of those, choose the version of PostgreSQL you'd like to upgrade to, then change your docker image to match:

pgautoupgrade/pgautoupgrade:17-bookworm

⁠"One shot" mode

If you just want to perform the upgrade without starting PostgreSQL afterwards, then you can use "One Shot" mode.

To do that, add an environment variable called PGAUTO_ONESHOT (equal to yes) when you run the container. Like this:

$ docker run --name pgauto -it \
	--mount type=bind,source=/path/to/your/database/directory,target=/var/lib/postgresql/data \
	-e POSTGRES_PASSWORD=password \
	-e PGAUTO_ONESHOT=yes \
	<NAME_OF_THE_PGAUTOUPGRADE_IMAGE>

⁠Skip reindexing

By default, all databases are reindexed after the migration, which can take some time if they are large. To skip reindexing, set the environment variable PGAUTO_REINDEX to no, for example:

$ docker run --name pgauto -it \
        --mount type=bind,source=/path/to/your/database/directory,target=/var/lib/postgresql/data \
        -e POSTGRES_PASSWORD=password \
        -e PGAUTO_REINDEX=no \
        <NAME_OF_THE_PGAUTOUPGRADE_IMAGE>

⁠Source code

This image is developed at: https://github.com/pgautoupgrade/docker-pgautoupgrade⁠. Feel free to get involved in developing, making suggestions, reporting bugs, etc. :D