add postgres 17 upgrade steps to 2.39.0 upgrade notes (#12585)

* postgres 17 upgrade steps

* more info

* more info

* improvements

* improvements

* improvements

* improvements

* improvements

Author: valentijnscholten

docs/content/en/open_source/upgrading/2.39.md

@@ -2,7 +2,114 @@
 title: 'Upgrading to DefectDojo Version 2.39.x'
 toc_hide: true
 weight: -20240903
-description: No special instructions.
+description: Major upgrade of Postgres 16 to 17
 exclude_search: true
 ---
-There are no special instructions for upgrading to 2.39.x. Check the [Release Notes](https://github.com/DefectDojo/django-DefectDojo/releases/tag/2.39.0) for the contents of the release.
+
+# PostgreSQL Major Version Upgrade in Docker Compose
+
+This release incorporates a major upgrade of Postgres. When using the default docker compose setup you'll need to upgrade the Postgres data folder before you can use Defect Dojo 2.39.0.
+
+There are lots of online guides to be found such as https://hub.docker.com/r/tianon/postgres-upgrade or https://github.com/pgautoupgrade/docker-pgautoupgrade.
+
+There's also the [official documentation on `pg_upgrade`](https://www.postgresql.org/docs/current/pgupgrade.html), but this doesn't work out of the box when using Docker containers.
+
+Sometimes it's easier to just perform the upgrade manually, which would look something like the steps below.
+It may need some tuning to your specific needs and docker compose setup. The guide is loosely based on https://simplebackups.com/blog/docker-postgres-backup-restore-guide-with-examples.
+If you already have a valid backup of the postgres 16 database, you can start at step 4.
+
+---
+
+## 0. Backup
+
+Always back up your data before starting and save it somewhere.
+Make sure the backup and restore is tested before continuing the steps below where the docker volume containing the database will be removed.
+
+## 1. Start the Old Postgres Container
+
+If you've acceidentally already updated your docker-compose.yml to the new versions, downgrade to postgres 16 for now:
+
+Edit your `docker-compose.yml` to use the old Postgres version (e.g., `postgres:16.4-alpine`):
+
+```yaml
+postgres:
+  image: postgres:16.4-alpine
+  ...
+```
+
+Start only the Postgres container which will now be 16.4:
+
+```bash
+docker compose up -d postgres
+```
+
+---
+
+## 2. Dump Your Database
+
+```bash
+docker compose exec -t postgres pg_dump -U defectdojo -Fc defectdojo -f /tmp/defectdojo.dump
+docker cp <postgres_container_name>:/tmp/defectdojo.dump defectdojo.dump
+```
+You can find the postgres_container_name via `docker container ls` or `docker ps`.
+
+---
+
+## 3. Stop Containers and Remove the Old Volume
+
+You can find the volume name via `docker volume ls`.
+
+```bash
+docker compose down
+docker volume rm <defectdojo_postgres_volume_name>
+```
+
+---
+
+## 4. Switch to the New Postgres Version
+
+Edit your `docker-compose.yml` to use the new version (e.g., `postgres:17.5-alpine`):
+
+```yaml
+postgres:
+  image: postgres:17.5-alpine
+  ...
+```
+
+---
+
+## 5. Start the New Postgres Container
+
+```bash
+docker compose up -d postgres
+```
+
+---
+
+## 6. Restore Your Database
+
+**Copy the dump file into the new container:**
+
+```bash
+docker cp defectdojo.dump <postgres_container_name>:/defectdojo.dump
+```
+
+**Restore inside the container:**
+
+```bash
+docker exec -it <postgres_container_name> bash
+pg_restore -U defectdojo -d defectdojo /defectdojo.dump
+```
+
+---
+
+## 7. Start the Rest of Your Services
+
+```bash
+docker compose up -d
+```
+
+---
+
+
+Check the [Release Notes](https://github.com/DefectDojo/django-DefectDojo/releases/tag/2.39.0) for the contents of the release.