{"id":13522553,"url":"https://github.com/pgautoupgrade/docker-pgautoupgrade","last_synced_at":"2025-03-31T22:31:47.798Z","repository":{"id":180089142,"uuid":"663862438","full_name":"pgautoupgrade/docker-pgautoupgrade","owner":"pgautoupgrade","description":"A PostgreSQL Docker container that automatically upgrades your database","archived":false,"fork":false,"pushed_at":"2024-10-24T03:30:10.000Z","size":123,"stargazers_count":617,"open_issues_count":11,"forks_count":21,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-10-24T13:52:17.770Z","etag":null,"topics":["docker","postgres","postgresql","postgresql-database","upgrade"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/pgautoupgrade/pgautoupgrade","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pgautoupgrade.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-08T09:44:32.000Z","updated_at":"2024-10-24T13:22:57.000Z","dependencies_parsed_at":"2023-11-15T10:40:18.035Z","dependency_job_id":"89ec8712-18f6-4090-afe5-16b107fde8ff","html_url":"https://github.com/pgautoupgrade/docker-pgautoupgrade","commit_stats":null,"previous_names":["justinclift/docker-pgautoupgrade","pgautoupgrade/docker-pgautoupgrade"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgautoupgrade%2Fdocker-pgautoupgrade","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgautoupgrade%2Fdocker-pgautoupgrade/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgautoupgrade%2Fdocker-pgautoupgrade/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgautoupgrade%2Fdocker-pgautoupgrade/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pgautoupgrade","download_url":"https://codeload.github.com/pgautoupgrade/docker-pgautoupgrade/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246552697,"owners_count":20795828,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","postgres","postgresql","postgresql-database","upgrade"],"created_at":"2024-08-01T06:00:48.886Z","updated_at":"2025-03-31T22:31:47.792Z","avatar_url":"https://github.com/pgautoupgrade.png","language":"Shell","funding_links":[],"categories":["Tools for Self-Hosting","Shell"],"sub_categories":["Development"],"readme":"This is a PostgreSQL Docker image to automatically upgrade\nyour database.\n\nIts whole purpose in life is to automatically detect the\nversion of PostgreSQL used in the existing PostgreSQL data\ndirectory, then automatically upgrade it (if needed) to the\nrequired version of PostgreSQL.\n\nAfter this, the PostgreSQL server starts and runs as per\nnormal.\n\nThe reason this Docker image is needed, is because the\nofficial Docker PostgreSQL image has no ability to handle\nversion upgrades, which leaves people to figure it out\nmanually (not great): https://github.com/docker-library/postgres/issues/37\n\n\u003e [!WARNING]\n\u003e Backup your data!\n\u003e This Docker image does an in-place upgrade of the database\n\u003e data, so if something goes wrong you are expected to already\n\u003e have backups you can restore from.\n\n\u003e [!IMPORTANT]\n\u003e Also, remove any healthchecks.\n\u003e Due to how we perform the update process, we had to implement our own healthcheck.\n\u003e So no extra healthcheck is needed.\n\n## How to use this image\n\nThis image is on Docker Hub:\n\nhttps://hub.docker.com/r/pgautoupgrade/pgautoupgrade\n\nTo always use the latest version of PostgreSQL, use the tag\n`latest`:\n\n    pgautoupgrade/pgautoupgrade:latest\n\nPlease note that our `latest` tag is based on Alpine Linux,\nwhereas the `latest` tag used by the official Docker\nPostgres container is based on Debian.\n\nIf you instead want to run a specific version of PostgreSQL\nthen pick a matching tag on our Docker Hub. For example, to\nuse PostgreSQL 17 you can use:\n\n    pgautoupgrade/pgautoupgrade:17-alpine\n\n\u003e [!NOTE]  \n\u003e The images available in Github Container Registry are for debugging\n\u003e purposes only. They are built from specific code branches for easier\n\u003e distribution and testing of fixes.\n\n### Debian vs Alpine based images\n\nThe default official Docker PostgreSQL image is Debian Linux\nbased, and upgrading from that to one of our Alpine Linux\nbased images doesn't always work out well.\n\nTo solve that problem, we have Debian based images\n(`17-bookworm` and `16-bookworm`) available now as well.\n\nTo use either of those, choose the version of PostgreSQL you'd\nlike to upgrade to, then change your docker image to match:\n\n    pgautoupgrade/pgautoupgrade:17-bookworm\n\n### \"One shot\" mode\n\nIf you just want to perform the upgrade without running PostgreSQL\nafterwards, then you can use \"[One Shot](https://github.com/pgautoupgrade/docker-pgautoupgrade/issues/13)\" mode.\n\nTo do that, add an environment variable called `PGAUTO_ONESHOT`\n(equal to `yes`) when you run the container.  Like this:\n\n```\n$ docker run --name pgauto -it \\\n\t--mount type=bind,source=/path/to/your/database/directory,target=/var/lib/postgresql/data \\\n\t-e POSTGRES_PASSWORD=password \\\n\t-e PGAUTO_ONESHOT=yes \\\n\t\u003cNAME_OF_THE_PGAUTOUPGRADE_IMAGE\u003e\n```\n\n### Reindexing\n\nBy default, all databases are reindexed after the migration, which can take some time if they are large.\nTo skip reindexing, set the environment variable `PGAUTO_REINDEX` to `no`, for example:\n\n```\n$ docker run --name pgauto -it \\\n\t--mount type=bind,source=/path/to/your/database/directory,target=/var/lib/postgresql/data \\\n\t-e POSTGRES_PASSWORD=password \\\n\t-e PGAUTO_REINDEX=no \\\n\t\u003cNAME_OF_THE_PGAUTOUPGRADE_IMAGE\u003e\n```\n\n\u003e [!WARNING]\n\u003e PG v15 and below do not support reindexing system tables in a database concurrently. This means, when we start the indexing operation, database locks are placed which do not allow for any modifications as long as the task is running. We recommend using PG v16 or later where this is not an issue.\n\n### Upgrading from a Bitnami container\n\nIf you used the Postgres image by Bitnami, we have made a couple of adjustments to make this upgrade work as well.\n\nThe Bitnami containers do not persist the `postgresql.conf` and `pg_hba.conf` file in the Postgres data directory. If we detect that these files are missing, we will copy a default version of these files into the data directory. If you request the \"one shot\" mode, these files will be removed again at the end of the upgrade process.\n\nThe official Postgres image, and therefore ours as well, use `999` as ID for the postgres user inside the container. Bitnami uses 1001. During the upgrade process, we make a copy of the data, which will be assigned to ID `999`. If you request the \"one shot\" mode, the original file permissions will be restored once the upgrade is completed.\n\nBe aware that we use the environment variables from the official Postgres image. Ensure you set `PGDATA` to the Bitnami folder (by default `/bitnami/postgresql/data`) and `POSTGRES_PASSWORD` to the password of your Postgres user.\n\nThe container has to run as `root` if using `one shot` mode, otherwise we are unable to restore the existing file permissions of your Postgres data directory. You can run the container as user `999`, but then you will have to manually apply the file permissions to your Postgres data directory.\n\n\u003e [!WARNING]\n\u003e As of writing this paragraph (14th of November, 2024), we only tested upgrading from Bitnami Postgres v13, v14, v15, v16 to v17. For these versions, we used the latest available container version. Bitnami's script and directory structure could change over time. If you note any issues upgrading from other versions, please provide the exact SHA of the image so we can try to replicate the issue.\n\n### One-shot mode in Kubernetes\n\nYou can run `pgautoupgrade` as an `initContainer` in Kubernetes to enable one-shot mode. Below you can find an example for an upgrade for a Bitnami Postgres container.\n\n```yaml\ninitContainers:\n- env:\n\t- name: PGAUTO_ONESHOT\n\t  value: \"yes\"\n\t- name: POSTGRES_DB\n\t  value: XXX\n\t- name: PGDATA\n\t  value: /bitnami/postgresql/data\n\t- name: POSTGRES_PASSWORD\n\t  value: password\nimage: pgautoupgrade/pgautoupgrade:17-bookworm\nname: upgrade-postgres\nsecurityContext:\n\trunAsUser: 0\nvolumeMounts:\n\t- mountPath: /bitnami/postgresql\n\t  name: YYY\n```\n\nThe value for `POSTGRES_PASSWORD` does not really matter, as it's never used in one-shot mode.\n\n# For Developers\n\n## Building the image\n\nTo build the development docker image, use:\n\n```\n$ make dev\n```\n\nThis will take a few minutes to create the \"pgautoupgrade:local\"\ndocker image, that you can use in your docker-compose.yml\nfiles.\n\n## Customising the image\n\n[Our wiki](https://github.com/pgautoupgrade/docker-pgautoupgrade/wiki)\nnow includes instructions for customising the image to include\nyour own extensions:\n\n\u0026nbsp; \u0026nbsp; https://github.com/pgautoupgrade/docker-pgautoupgrade/wiki/Including-Extensions-(PostGIS)\n\n## Breakpoints in the image\n\nThere are (at present) two predefined er... \"breakpoints\"\nin the image.  When you run the image with either\nof them, then the image will start up and keep running,\nbut the docker-entrypoint script will pause at the chosen\nlocation.\n\nThis way, you can `docker exec` into the running container to\ntry things out, do development, testing, debugging, etc.\n\n### Before breakpoint\n\nThe `before` breakpoint stops just before the `pg_upgrade`\npart of the script runs, so you can try alternative things\ninstead.\n\n```\n$ make before\n```\n\n### Server breakpoint\n\nThe `server` breakpoint stops after the existing `pg_upgrade`\nscript has run, but before the PostgreSQL server starts.  Useful\nif you want to investigate the results of the upgrade prior to\nPostgreSQL acting on them.\n\n```\n$ make server\n```\n\n## Testing the image\n\nTo run the tests, use:\n\n```\n$ make test\n```\n\nThe test script imports the AdventureWorks database (ported from Microsoft\nland) into an older PG version, then starts the pgautoupgrade container to\nupdate the database to the latest PostgreSQL version.\n\nIt then checks that the database files were indeed updated\nto the newest PostgreSQL release, and outputs an obvious\nSUCCESS/FAILURE message for that loop.\n\nThe test runs in a loop, testing (in sequence) upgrades from\nPostgreSQL versions 9.5, 9.6, 10.x, 11.x, 12.x, 13.x, 14.x, 15.x., 16.x and\n17.x.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgautoupgrade%2Fdocker-pgautoupgrade","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpgautoupgrade%2Fdocker-pgautoupgrade","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgautoupgrade%2Fdocker-pgautoupgrade/lists"}