diff --git a/README.md b/README.md index f6c6802..359e664 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,61 @@ -This is a PostgreSQL Docker container that automatically -upgrades your database. +This is a PostgreSQL Docker image to automatically upgrade +your database. -It's whole purpose in life is to automatically detect the +Its whole purpose in life is to automatically detect the version of PostgreSQL used in the existing PostgreSQL data -directory, and automatically upgrade it (if needed) to the +directory, then automatically upgrade it (if needed) to the required version of PostgreSQL. After this, the PostgreSQL server starts and runs as per normal. -The reason this Docker container is needed, is because -the official Docker PostgreSQL container has no ability -to handle version upgrades, which leaves people to figure -it out manually (not great): https://github.com/docker-library/postgres/issues/37 +The reason this Docker image is needed, is because the +official Docker PostgreSQL image has no ability to handle +version upgrades, which leaves people to figure it out +manually (not great): https://github.com/docker-library/postgres/issues/37 ## WARNING! Backup your data! -This Docker container does an in-place upgrade of the database +This Docker image 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. -## How to use this container +## How to use this image -This container is on Docker Hub: +This image is on Docker Hub: https://hub.docker.com/r/pgautoupgrade/pgautoupgrade -To always use the latest version of PostgreSQL, use -the tag `latest`: +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 on our Docker Hub. For example, -to use PostgreSQL 15 you can use: +then pick a matching tag on our Docker Hub. For example, to +use PostgreSQL 15 you can use: pgautoupgrade/pgautoupgrade:15-alpine3.8 +### "One shot" mode + +If you just want to perform the upgrade without starting PostgreSQL +afterwards, then you can use "[One Shot](https://github.com/pgautoupgrade/docker-pgautoupgrade/issues/13)" 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 \ + +``` + # For Developers -## Building the container +## Building the image To build the development docker image, use: @@ -48,14 +64,14 @@ $ make dev ``` This will take a few minutes to create the "pgautoupgrade:latest" -docker container, that you can use in your docker-compose.yml +docker image, that you can use in your docker-compose.yml files. -## Breakpoints in the container +## Breakpoints in the image There are (at present) two predefined er... "breakpoints" -in the container. When you run the container with either -of them, then the container will start up and keep running, +in the image. When you run the image with either +of them, then the image will start up and keep running, but the docker-entrypoint script will pause at the chosen location. @@ -83,7 +99,7 @@ PostgreSQL acting on them. $ make server ``` -## Testing the container image +## Testing the image To run the tests, use: @@ -93,12 +109,13 @@ $ make test The test script creates an initial PostgreSQL database for Redash using an older PG version, then starts Redash using -the above "automatic updating" PostgreSQL container to -update the database to the latest PostgreSQL version. +the above "automatic updating" PostgreSQL image to update +the database to the latest PostgreSQL version. It then checks that the database files were indeed updated to the newest PostgreSQL release, and outputs an obvious SUCCESS/FAILURE message for that loop. -The test runs in a loop, testing (in sequence) PostgreSQL -versions 9.5, 9.6, 10.x, 11.x, 12.x, 13.x, and 14.x. +The test runs in a loop, testing (in sequence) upgrades from +PostgreSQL versions 9.5, 9.6, 10.x, 11.x, 12.x, 13.x, 14.x +and 15.x. diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh index 6e293db..c0485b4 100755 --- a/docker-entrypoint.sh +++ b/docker-entrypoint.sh @@ -566,7 +566,13 @@ _main() { sleep 5 done else - exec "$@" + if [ "x${PGAUTO_ONESHOT}" = "xyes" ]; then + echo "*****************************************************************************************************" + echo "'One shot' automatic upgrade was requested, so exiting now rather than starting the PostgreSQL server" + echo "*****************************************************************************************************" + else + exec "$@" + fi fi }