From 15648342ddbf6a3f20f3e22e4e1e5a1f162f8739 Mon Sep 17 00:00:00 2001 From: nishanthabimanyu Date: Mon, 9 Mar 2026 16:17:43 +0000 Subject: [PATCH] docs(postgres): add migration guide and update to postgres 15.17 --- docs/04-operations/01-site-operations.md | 13 ++---- .../03-postgres-major-version-upgrade.md | 40 +++++++++++++++++++ overrides/compose.postgres.yaml | 2 +- 3 files changed, 45 insertions(+), 10 deletions(-) create mode 100644 docs/06-migration/03-postgres-major-version-upgrade.md diff --git a/docs/04-operations/01-site-operations.md b/docs/04-operations/01-site-operations.md index 1520d6aa..6f20a332 100644 --- a/docs/04-operations/01-site-operations.md +++ b/docs/04-operations/01-site-operations.md @@ -15,17 +15,12 @@ docker-compose exec backend bench new-site --mariadb-user-host-login-scope=% --d If you need to install some app, specify `--install-app`. To see all options, just run `bench new-site --help`. -To create Postgres site (assuming you already use [Postgres compose override](../02-setup/05-overrides.md)) you need have to do set `root_login` and `root_password` in common config before that: +To create a Postgres site (assuming you already use [Postgres compose override](../02-setup/05-overrides.md)), the `root_login` and `root_password` are now automatically set by the `configurator`. For major version upgrades, please refer to the [Postgres Migration Guide](../06-migration/03-postgres-major-version-upgrade.md). + +To create a new Postgres site: ```sh -docker-compose exec backend bench set-config -g root_login -docker-compose exec backend bench set-config -g root_password -``` - -Also command is slightly different: - -```sh -docker-compose exec backend bench new-site --mariadb-user-host-login-scope=% --db-type postgres --admin-password +docker-compose exec backend bench new-site --db-type postgres --admin-password ``` ## Push backup to S3 storage diff --git a/docs/06-migration/03-postgres-major-version-upgrade.md b/docs/06-migration/03-postgres-major-version-upgrade.md new file mode 100644 index 00000000..d6339f93 --- /dev/null +++ b/docs/06-migration/03-postgres-major-version-upgrade.md @@ -0,0 +1,40 @@ +# PostgreSQL Major Version Upgrade (v13 to v15) + +Upgrading PostgreSQL from version 13 to 15 is a major version jump. Since PostgreSQL does not support in-place data directory upgrades, existing users must manually migrate their data using `pg_dump`. + +### **Migration Steps** + +1. **Backup Existing Data (Version 13):** + Before updating your compose file, ensure your containers are running and perform a dump of all databases. + ```bash + docker exec -it -db-1 pg_dumpall -U postgres > full_dump.sql + ``` + +2. **Stop and Remove Containers:** + ```bash + docker compose down + ``` + +3. **Delete Old Data Volume:** + PostgreSQL 15 cannot read data created by version 13. You must remove the existing volume (Warning: this deletes the old data directory). + ```bash + docker volume rm _db-data + ``` + +4. **Update Image and Start (Version 15):** + Update your `overrides/compose.postgres.yaml` (or pull the latest changes) and start the containers. + ```bash + docker compose up -d + ``` + +5. **Restore Data:** + Restore the dump into the new PostgreSQL 15 instance. + ```bash + cat full_dump.sql | docker exec -i -db-1 psql -U postgres + ``` + +6. **Verify and Clean Up:** + Ensure your sites are working correctly with `bench migrate` and then remove the `full_dump.sql` file. + ```bash + docker exec -it -backend-1 bench --site all migrate + ``` diff --git a/overrides/compose.postgres.yaml b/overrides/compose.postgres.yaml index b3222f6b..376758f8 100644 --- a/overrides/compose.postgres.yaml +++ b/overrides/compose.postgres.yaml @@ -8,7 +8,7 @@ services: condition: service_healthy db: - image: postgres:15-alpine + image: postgres:15.17 command: [] healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"]