docs: PostgreSQL major upgrade for RHDH Local

[zdrapela]

Description

Align RHDH Local's optional Compose Postgres with the PG18 direction from RHIDP-13956:

• Bump the optional db image example to registry.redhat.io/rhel10/postgresql-18
• Document a version-neutral major-upgrade path using sclorg POSTGRESQL_UPGRADE=copy
• Keep in-memory SQLite as the default database

Tracked by RHIDP-15765 (child of RHIDP-13956). Related product docs work remains RHIDP-14594 (chart/operator); this PR is RHDH Local only. Procedure inspired by rhdh#5139.

Which issue(s) does this PR fix or relate to

• Fixes RHIDP-15765
• Epic: RHIDP-13956
• Related: RHIDP-14594

PR acceptance criteria

• Tests updated and passing
• Documentation updated
• Built-in TechDocs updated if needed. Note that TechDocs changes may need to be reviewed by a Product Manager and/or Architect to ensure content accuracy, clarity, and alignment with user needs.

How to test changes / Special notes to the reviewer

Locally verified end-to-end:

1. Start optional db on rhel8/postgresql-16, seed proof data, bring up RHDH (:1.10) → HTTP 200
2. Stop RHDH; switch to rhel10/postgresql-18 with POSTGRESQL_UPGRADE=copy (same volume)
3. Confirm SHOW server_version 16.x → 18.x and proof data survives (Upgrade Complete in db logs)
4. Refresh collation versions if warned; remove POSTGRESQL_UPGRADE; --force-recreate db
5. Start RHDH again → HTTP 200, PostgreSQL store, restart count 0

[rhdh-qodo-merge]

PR Summary by Qodo

Docs: Upgrade RHDH Local optional Postgres example to PG18 + major-upgrade guide

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Bump the optional Compose Postgres example image to rhel10/postgresql-18.
• Document a version-neutral major upgrade path using POSTGRESQL_UPGRADE=copy.
• Clarify Podman/Docker command usage and env (.env) expectations for POSTGRES_* values.

Diagram

graph TD
  U["User"] --> G["postgresql-guide.md"] --> C["compose.yaml"] --> PC["Postgres container (PG18)"] --> V[("PG data volume")]
  G --> P["podman compose"] --> PC
  U --> R["RHDH Local"] --> PC

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Logical backup/restore (pg_dump/pg_restore)

• ➕ Works across broader version gaps and container implementations
• ➕ Avoids relying on image-specific pg_upgrade wrappers
• ➖ More steps and longer downtime for larger datasets
• ➖ Requires creating/restoring roles/dbs and verifying extensions/config

2. Use an external/managed Postgres for local dev

• ➕ Decouples RHDH Local from container image lifecycle changes
• ➕ Upgrade/maintenance handled outside the Compose stack
• ➖ Higher setup friction for local developers
• ➖ Less representative of the documented optional Compose path

Recommendation: For RHDH Local’s optional Compose database, documenting sclorg’s built-in POSTGRESQL_UPGRADE=copy is the best fit: it keeps the existing volume, is relatively low-effort for users, and aligns with the chosen RHEL10/PG18 image direction. The guide appropriately adds guardrails (backup, stop writes, remove POSTGRESQL_UPGRADE afterward) while staying version-neutral.

Files changed (2) +88 / -11

Documentation (1) +87 / -10

postgresql-guide.mdRevise Postgres setup notes and add major-upgrade procedure +87/-10

Revise Postgres setup notes and add major-upgrade procedure

• Clarifies registry access requirements, Podman/Docker command substitutions, and the expectation to populate '.env' with 'POSTGRES_*' values. Updates the example image to rhel10/postgresql-18 and adds a version-neutral major-upgrade section using 'POSTGRESQL_UPGRADE=copy', including collation refresh and post-upgrade recreate steps.

docs/rhdh-local-guide/postgresql-guide.md

Other (1) +1 / -1

compose.yamlUpdate optional db image example to rhel10/postgresql-18 +1/-1

Update optional db image example to rhel10/postgresql-18

• Updates the commented-out Compose 'db' service example to reference 'registry.redhat.io/rhel10/postgresql-18:latest' instead of the older rhel8/postgresql-16 image, aligning the optional local Postgres example with the PG18 direction.

compose.yaml

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Context used

⚠️ Tickets: not configured — ticket URL found in PR but could not be fetched — check ticket provider credentials

✅ Cross-repo context

  Not relevant to this PR: redhat-developer/rhdh

  Not relevant to this PR: redhat-developer/rhdh-plugins

1. Postgres config not applied 🐞 Bug ≡ Correctness

Description

The PostgreSQL guide’s primary snippet configures a top-level database: key, but RHDH Local
actually configures SQLite under backend.database in the default config that is always loaded, so
the Postgres settings may not override SQLite and RHDH can continue using in-memory SQLite (or fail
validation). The guide should instruct users to override backend.database in
configs/app-config/app-config.local.yaml (and/or explicitly remove/override the default
backend.database) rather than relying on a top-level database: block.

Code

docs/rhdh-local-guide/postgresql-guide.md[69]

+   If you need `pluginDivisionMode: schema` (one database, one schema per plugin — useful when the DB user cannot create multiple databases), use this `backend.database` block in `app-config.local.yaml` instead of the snippet above:

Relevance

⭐⭐ Medium

Touches debated guide config shape; prior review kept top-level database: snippet despite
suggestion to remove wrapper.

PR-#61

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

RHDH Local always loads configs/app-config/app-config.yaml (patched) and only optionally adds
configs/app-config/app-config.local.yaml, and the default config defines SQLite under
backend.database. The guide’s main Postgres example uses a top-level database: key, which does
not override backend.database, so SQLite can remain active.

wait-for-plugins-and-start.sh[14-72]
configs/app-config/app-config.yaml[168-172]
docs/rhdh-local-guide/postgresql-guide.md[49-81]
configs/app-config/app-config.local.example.yaml[1-20]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`docs/rhdh-local-guide/postgresql-guide.md` shows a primary Postgres configuration snippet using a top-level `database:` key and suggests commenting out SQLite in `app-config.local.yaml`. However, the runtime loads `configs/app-config/app-config.yaml` (which contains SQLite under `backend.database`) and then optionally loads `configs/app-config/app-config.local.yaml`. A top-level `database:` key does not override `backend.database`, so users following the guide can end up still using SQLite.

### Issue Context
RHDH Local’s entrypoint loads configs in this order: default + dynamic plugins + patched config + optional user local config. The default config currently sets `backend.database` to SQLite.

### Fix Focus Areas
- docs/rhdh-local-guide/postgresql-guide.md[49-81]
- wait-for-plugins-and-start.sh[14-72]
- configs/app-config/app-config.yaml[168-172]

### Proposed fix
1. Replace the main Postgres snippet to use `backend.database:` (not top-level `database:`), matching the default config structure.
2. Update the “comment out SQLite” instruction to reference `configs/app-config/app-config.yaml` (where SQLite is actually defined) OR, preferably, show how to override `backend.database` in `configs/app-config/app-config.local.yaml` without editing the default file.
3. Ensure the `pluginDivisionMode: schema` variant is presented as a small variation of the same `backend.database` block (so both examples share the same correct key path).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Upgrade commands assume db name 🐞 Bug ☼ Reliability

Description

The new upgrade procedure uses podman exec db / podman inspect db, but the earlier Compose
snippet in the same doc omits container_name: db, so users who copy/paste the snippet (instead of
uncommenting the repo’s Compose block) will not have a container named db and the upgrade commands
will fail. Either include container_name: db in the snippet or switch the commands to `podman
compose exec db ...` to target the service name reliably.

Code

docs/rhdh-local-guide/postgresql-guide.md[R95-98]

+   ```sh
+   podman exec db psql -U postgres -c "SHOW server_version;"
+   podman inspect db --format '{{.Config.Image}}'
+   ```

Relevance

⭐⭐⭐ High

Team historically accepts doc fixes improving command/snippet reliability and avoiding brittle
compose/podman usage mismatches.

PR-#147
PR-#61

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The repo’s Compose example sets the db container name explicitly, but the guide’s shown YAML omits
it while the new upgrade steps assume the name db for exec/inspect. That mismatch makes the
new upgrade steps brittle for readers who apply the abbreviated snippet.

compose.yaml[6-19]
docs/rhdh-local-guide/postgresql-guide.md[20-37]
docs/rhdh-local-guide/postgresql-guide.md[93-99]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The upgrade section hard-codes a container name (`db`) in `podman exec db ...` / `podman inspect db ...`. However, the earlier Compose snippet shown in the doc omits `container_name: db`, so users who apply the snippet directly may end up with an auto-generated container name and the upgrade commands won’t work.

### Issue Context
The repository’s actual `compose.yaml` db block includes `container_name: db`, but the doc snippet is abbreviated and can be treated as authoritative by readers.

### Fix Focus Areas
- docs/rhdh-local-guide/postgresql-guide.md[20-37]
- docs/rhdh-local-guide/postgresql-guide.md[93-99]
- compose.yaml[6-19]

### Proposed fix
Choose one:
1. Add `container_name: db` to the doc’s db snippet.
2. Prefer `podman compose exec db ...` (and Docker equivalent `docker compose exec db ...`) throughout the upgrade steps, and replace `podman inspect db ...` with a service-based alternative (e.g., inspect the container id from `podman compose ps -q db`).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[rm3l]

Looks good, but IMO should be merged into the upcoming dev branch for 2.1, not main.

/hold

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud