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.

Replacement for closed #275 (recreated from an in-repo branch so it can participate in a GitHub stack with #276).

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

Made with Cursor

[zdrapela]

Replacement for closed #275 (same commits). Part of GitHub stack #279 with #276 on top. Recreated from an in-repo branch because GitHub stacked PRs cannot include fork PRs.

[rhdh-qodo-merge]

PR Summary by Qodo

Docs: Align optional Compose Postgres to PG18 and document major upgrades

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Update optional Compose Postgres example to use rhel10/postgresql-18.
• Clarify env setup (.env/default.env) and Podman vs Docker command usage.
• Add a version-neutral major upgrade procedure using POSTGRESQL_UPGRADE=copy.

Diagram

graph TD
  A["PostgreSQL guide"] --> B[".env / default.env"] --> C["compose.yaml"] --> D["Postgres container (PG18)"] --> E[("Data volume")]
  C["compose.yaml"] --> F["RHDH container"] --> D["Postgres container (PG18)"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Logical dump/restore (pg_dump/pg_restore)

• ➕ Works even when the target image does not support a direct major-hop upgrade
• ➕ More explicit control over what is migrated
• ➖ More steps and more time; requires enough temporary storage
• ➖ Higher chance of user error for a local-dev flow

2. Side-by-side new db + app cutover

• ➕ Keeps the original volume untouched until verification completes
• ➕ Can be safer for cautious users
• ➖ More Compose complexity (ports, service naming, connection switching)
• ➖ Still needs a migration mechanism (dump/restore or replication)

3. Use an external/managed Postgres for persistence

• ➕ Avoids local container major upgrades entirely
• ➕ Closer to production-like persistence for some workflows
• ➖ Adds infrastructure/accounts/network dependencies
• ➖ Out of scope for a simple local quickstart

Recommendation: Keep the documented approach: sclorg’s supported POSTGRESQL_UPGRADE=copy is the most version-neutral and least error-prone path for RHDH Local users who already have a persisted volume. Consider optionally adding a short fallback note for pg_dump/pg_restore when a direct hop isn’t supported by POSTGRESQL_PREV_VERSION.

Files changed (2) +91 / -11

Documentation (1) +90 / -10

postgresql-guide.mdRefresh Postgres enablement instructions and add major-upgrade runbook +90/-10

Refresh Postgres enablement instructions and add major-upgrade runbook

• Clarifies registry login requirements, Podman vs Docker command substitution, and '.env' setup for 'POSTGRES_*' variables. Updates the example image to PostgreSQL 18 and adds a version-neutral major upgrade procedure using 'POSTGRESQL_UPGRADE=copy', including collation refresh and container recreation guidance without deleting volumes.

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

Other (1) +1 / -1

compose.yamlBump optional Postgres example image to rhel10/postgresql-18 +1/-1

Bump optional Postgres example image to rhel10/postgresql-18

• Updates the commented-out optional 'db' service example to reference 'registry.redhat.io/rhel10/postgresql-18:latest', aligning the local Compose guidance with the PG18 direction.

compose.yaml

[rhdh-qodo-merge]

Code Review by Qodo

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

1. No existing-volume upgrade warning ✓ Resolved 🐞 Bug ☼ Reliability ⭐ New

Description

The main “Using a PostgreSQL database” steps now show the PG18 image, but they don’t explicitly warn
that users with an existing Postgres data volume from an older major version must follow the new
upgrade procedure first. Without that callout, an existing setup can fail to start the DB when the
image major version changes.

Code

docs/rhdh-local-guide/postgresql-guide.md[R21-22]

   db:
-     image: "registry.redhat.io/rhel8/postgresql-16:latest"
+     image: "registry.redhat.io/rhel10/postgresql-18:latest"

Relevance

●●● Strong

Docs changes adding explicit destructive/upgrade cautions are typically accepted to prevent common
user breakage.

PR-#56
PR-#239

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The updated ‘normal setup’ snippet now points to rhel10/postgresql-18, while the newly added
upgrade section documents an explicit major-upgrade process using POSTGRESQL_UPGRADE=copy and
warns about keeping the existing data volume—indicating the main setup flow should explicitly route
existing users to that procedure.

docs/rhdh-local-guide/postgresql-guide.md[18-37]
docs/rhdh-local-guide/postgresql-guide.md[83-90]

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 guide’s primary setup path now uses a PostgreSQL 18 image, but it does not clearly direct *existing* users (who already have a persisted `/var/lib/pgsql/data`) to the “Upgrading PostgreSQL” section before changing the image.

## Issue Context
The same document introduces a major-upgrade flow using `POSTGRESQL_UPGRADE=copy`, which implies that simply swapping the image tag is not sufficient for users with an existing data directory from a previous major version.

## Fix Focus Areas
- docs/rhdh-local-guide/postgresql-guide.md[18-37]
- docs/rhdh-local-guide/postgresql-guide.md[83-90]

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

---

2. Hardcoded postgres user ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new “Upgrading PostgreSQL” section hardcodes psql -U postgres in multiple commands, which will
fail for users who override POSTGRES_USER (supported via default.env/.env and referenced
elsewhere in the same guide). This can block the documented upgrade/verification steps even though
the compose/db configuration is intended to be customizable.

Code

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

+   podman exec db psql -U postgres -c "SHOW server_version;"

Relevance

●●● Strong

Docs previously updated to avoid hardcoding Postgres values; should use POSTGRES_USER instead of `-U
postgres`.

PR-#61

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The upgrade section hardcodes the postgres role (-U postgres) while the repo’s env defaults and
earlier config snippet explicitly support a configurable POSTGRES_USER, making the new commands
inconsistent with the documented configuration mechanism.

docs/rhdh-local-guide/postgresql-guide.md[59-67]
docs/rhdh-local-guide/postgresql-guide.md[93-98]
docs/rhdh-local-guide/postgresql-guide.md[125-127]
docs/rhdh-local-guide/postgresql-guide.md[133-138]
default.env[2-6]

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 instructions use `psql -U postgres` even though the setup supports customizing the DB user via `POSTGRES_USER`. This breaks the documented commands when `POSTGRES_USER` is not `postgres`.

## Issue Context
- `default.env` defines `POSTGRES_USER` and users are explicitly told they may copy/override `POSTGRES_*` values.
- The guide’s app config example uses `${POSTGRES_USER}`, but the upgrade commands don’t.

## Fix Focus Areas
- docs/rhdh-local-guide/postgresql-guide.md[93-138]

### Suggested change
Update all `podman exec db psql -U postgres ...` commands to use the configured user, e.g.:

```sh
podman exec db sh -c 'psql -U "${POSTGRES_USER:-postgres}" -c "SHOW server_version;"'
```

And similarly for the collation refresh commands:

```sh
podman exec db sh -c 'psql -U "${POSTGRES_USER:-postgres}" -c "ALTER DATABASE postgres REFRESH COLLATION VERSION;"'
```

(Using `sh -c` ensures `$POSTGRES_USER` expands from the container environment loaded via `env_file`.)

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

---

3. Redundant env copy guidance ✓ Resolved 🐞 Bug ⚙ Maintainability ⭐ New

Description

The PostgreSQL guide instructs copying POSTGRES_* values from default.env into .env, even
though compose.yaml already loads both files into the containers. This encourages drift-prone
duplication where user-local .env can unintentionally become a stale fork of the repo defaults.

Code

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

+Copy the `POSTGRES_*` values from `default.env` into your project `.env` (or ensure they are set in the environment).

Relevance

●●● Strong

Team prefers .env as override via env_file; discourages drift-prone copying from tracked defaults.

PR-#149

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new sentence explicitly directs users to copy defaults into .env, but the repo already injects
both default.env and .env via env_file, and other docs define .env as an override file
rather than a copy of defaults.

docs/rhdh-local-guide/postgresql-guide.md[8-16]
compose.yaml[6-15]
compose.yaml[24-32]
docs/rhdh-local-guide/configuration.md[4-50]

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` tells users to *copy* all `POSTGRES_*` values from `default.env` into `.env`. In this repo, `.env` is intended to override or add only the variables you want to change, not duplicate defaults.

## Issue Context
Both `default.env` and optional `.env` are already injected into containers via `env_file` in `compose.yaml`, so copying defaults is redundant and can lead to config drift.

## Fix Focus Areas
- docs/rhdh-local-guide/postgresql-guide.md[8-12]

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

---

4. Ambiguous compose down warning ✓ Resolved 🐞 Bug ≡ Correctness ⭐ New

Description

The upgrade section uses bare compose down --volumes in warnings, despite the same guide
standardizing on podman compose / docker compose. This inconsistency makes the
destructive-operation warning easier to misread or miscopy.

Code

docs/rhdh-local-guide/postgresql-guide.md[R117-118]

+4. Recreate and start the `db` **container** so it boots the new image against the **existing** data volume (do not run `compose down --volumes`):
+

Relevance

●●● Strong

Repo routinely standardizes docs commands to explicit podman compose/docker compose forms for
consistency.

PR-#56
PR-#147

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The guide explicitly states the commands are podman/podman compose (or Docker equivalents), but
later references a bare compose down --volumes (and repeats the same pattern in “What not to do”),
which is inconsistent with the documented convention.

docs/rhdh-local-guide/postgresql-guide.md[8-10]
docs/rhdh-local-guide/postgresql-guide.md[117-121]
docs/rhdh-local-guide/postgresql-guide.md[156-163]
docs/rhdh-local-guide/operating-rhdh-local.md[228-248]

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 instructions warn against `compose down --volumes` but the document’s command convention is `podman compose` / `docker compose`. The warning should use the same explicit prefixes (and consistent `-v`/`--volumes` forms) to avoid ambiguity.

## Issue Context
This warning appears in the upgrade steps and again in the “What not to do” list.

## Fix Focus Areas
- docs/rhdh-local-guide/postgresql-guide.md[117-121]
- docs/rhdh-local-guide/postgresql-guide.md[156-163]

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

---

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

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

Previous review results

Review updated until commit 9d27ea3

Results up to commit d056cca ⚖️ Balanced

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Hardcoded postgres user ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new “Upgrading PostgreSQL” section hardcodes psql -U postgres in multiple commands, which will
fail for users who override POSTGRES_USER (supported via default.env/.env and referenced
elsewhere in the same guide). This can block the documented upgrade/verification steps even though
the compose/db configuration is intended to be customizable.

Code

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

+   podman exec db psql -U postgres -c "SHOW server_version;"

Relevance

●●● Strong

Docs previously updated to avoid hardcoding Postgres values; should use POSTGRES_USER instead of `-U
postgres`.

PR-#61

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The upgrade section hardcodes the postgres role (-U postgres) while the repo’s env defaults and
earlier config snippet explicitly support a configurable POSTGRES_USER, making the new commands
inconsistent with the documented configuration mechanism.

docs/rhdh-local-guide/postgresql-guide.md[59-67]
docs/rhdh-local-guide/postgresql-guide.md[93-98]
docs/rhdh-local-guide/postgresql-guide.md[125-127]
docs/rhdh-local-guide/postgresql-guide.md[133-138]
default.env[2-6]

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 instructions use `psql -U postgres` even though the setup supports customizing the DB user via `POSTGRES_USER`. This breaks the documented commands when `POSTGRES_USER` is not `postgres`.

## Issue Context
- `default.env` defines `POSTGRES_USER` and users are explicitly told they may copy/override `POSTGRES_*` values.
- The guide’s app config example uses `${POSTGRES_USER}`, but the upgrade commands don’t.

## Fix Focus Areas
- docs/rhdh-local-guide/postgresql-guide.md[93-138]

### Suggested change
Update all `podman exec db psql -U postgres ...` commands to use the configured user, e.g.:

```sh
podman exec db sh -c 'psql -U "${POSTGRES_USER:-postgres}" -c "SHOW server_version;"'
```

And similarly for the collation refresh commands:

```sh
podman exec db sh -c 'psql -U "${POSTGRES_USER:-postgres}" -c "ALTER DATABASE postgres REFRESH COLLATION VERSION;"'
```

(Using `sh -c` ensures `$POSTGRES_USER` expands from the container environment loaded via `env_file`.)

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

---

[zdrapela]

/hold until we have dev branch ready as the target.

[rm3l]

/hold until we have dev branch ready as the target.

@zdrapela #282 has been merged and I've created the dev branch. Feel free to update the base branch for this PR. Thanks.

[zdrapela]

Retargeted from main to dev per the main/dev branching strategy. Rebased onto upstream/dev and re-linked as GitHub stack #286 with #276 on top.

[zdrapela]

/unhold

[rhdh-qodo-merge]

Code review by qodo was updated up to the latest commit 8ffe4de

[zdrapela]

Addressed the Qodo review findings in 2ec1481:

1. Warning for existing volumes before major image bumps → link to Upgrading
2. psql uses ${POSTGRES_USER:-postgres} via sh -c
3. .env is overrides-only (no copy-all POSTGRES_* from default.env)
4. Volume-deletion warnings use podman compose down --volumes / docker compose down --volumes

Restacked #276 onto this tip so the overlay PR stays intact.

[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

[zdrapela]

@rm3l I fixed issues that Qodo flagged and the PR stack should be ready to review