fix: optional Postgres via compose-with-db overlay

[zdrapela]

Description

Fixes RHDHBUGS-1865: enabling the optional PostgreSQL service no longer requires uncommenting blocks in the default compose.yaml (which caused merge conflicts on pull).

• Add compose-with-db.yaml overlay (same pattern as compose-with-corporate-proxy.yaml / compose-dynamic-plugins-root.yaml)
• Point compose.yaml at the overlay instead of a commented db service
• Update the PostgreSQL guide for -f compose.yaml -f compose-with-db.yaml, including a combined example with compose-with-corporate-proxy.yaml
• Major upgrades use temporary gitignored compose.override.yaml + POSTGRES_IMAGE (do not edit tracked compose-with-db.yaml)

Stacked on #278 (docs/pg16-to-pg18-upgrade) — GitHub stack #286 targeting dev.

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

• Fixes RHDHBUGS-1865
• Depends on docs: PostgreSQL major upgrade for RHDH Local #278

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

1. Do not edit compose.yaml for Postgres
2. podman login registry.redhat.io
3. Copy POSTGRES_* into .env; switch app-config.local.yaml from SQLite to pg as in the guide
4. podman compose -f compose.yaml -f compose-with-db.yaml up -d → db healthy, RHDH up
5. Optional: podman compose -f compose.yaml -f compose-with-db.yaml -f compose-with-corporate-proxy.yaml config merges db + proxy + rhdh.depends_on
6. npx --yes dclint compose-with-db.yaml → 0 errors

[zdrapela]

Linked into GitHub stack #279 with gh stack: #278 (bottom) → #276 (top). Note: the previous bottom PR #275 was closed because stacks cannot include fork PRs; #278 is the same commits from redhat-developer:docs/pg16-to-pg18-upgrade.

[rhdh-qodo-merge]

PR Summary by Qodo

Fix optional PostgreSQL enablement via compose-with-db overlay

🐞 Bug fix 📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Add a dedicated Compose overlay to enable PostgreSQL without editing tracked compose.yaml.
• Update compose.yaml and env defaults to reference the overlay-based workflow.
• Refresh PostgreSQL docs, including upgrade steps using gitignored compose.override.yaml.

Diagram

graph TD
  Dev(["Developer"]) -->|"-f compose.yaml"| Base["compose.yaml"] --> RHDH(["RHDH service"])
  Dev(["Developer"]) -->|"-f compose-with-db.yaml"| DBOverlay["compose-with-db.yaml"] --> DB[("Postgres db")]
  DBOverlay["compose-with-db.yaml"] -->|"adds depends_on"| RHDH(["RHDH service"])
  UpgradeOverride["compose.override.yaml (temp)"] -->|"POSTGRESQL_UPGRADE"| DB[("Postgres db")]
  RHDH(["RHDH service"]) -. "waits for healthy" .-> DB[("Postgres db")]

  subgraph Legend
    direction LR
    _cfg["Compose file"] ~~~ _svc(["Service"]) ~~~ _db[("Database")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Use Compose profiles (db behind a profile)

• ➕ Single compose.yaml; users run --profile db instead of multiple -f files
• ➕ Compose auto-load behavior (including override) is more predictable in some setups
• ➖ Requires reorganizing the base compose file and service definitions
• ➖ May diverge from the repo’s established pattern of overlay files (proxy, dynamic plugins root)

2. Keep db commented in compose.yaml (status quo)

• ➕ No new files; minimal conceptual overhead
• ➖ Encourages editing tracked compose.yaml, causing frequent merge conflicts and local drift
• ➖ Harder to document and automate consistently

Recommendation: Keep the overlay approach. It matches existing optional overlays in this repo, avoids merge-conflict-prone edits to tracked compose.yaml, and cleanly supports advanced workflows (e.g., corporate proxy overlay + db overlay). The added guidance to use a gitignored compose.override.yaml for one-time major upgrades is also safer than asking users to edit tracked overlay files.

Files changed (5) +85 / -65

Bug fix (1) +2 / -23

compose.yamlRemove commented Postgres block; point users to overlay workflow +2/-23

Remove commented Postgres block; point users to overlay workflow

• Deletes the previously commented-out 'db' service and 'depends_on' guidance to prevent tracked-file edits. Replaces it with a short comment directing users to merge 'compose-with-db.yaml' for optional PostgreSQL usage.

compose.yaml

Documentation (1) +31 / -42

postgresql-guide.mdUpdate Postgres guide to use compose-with-db overlay and upgrade override flow +31/-42

Update Postgres guide to use compose-with-db overlay and upgrade override flow

• Rewrites the enablement steps to use 'podman compose -f compose.yaml -f compose-with-db.yaml ...', including a combined example with the corporate proxy overlay. Updates major-upgrade instructions to pin the image via '.env' and use a temporary gitignored 'compose.override.yaml' that must be explicitly included when overlays are used.

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

Other (3) +52 / -0

compose-with-db.yamlIntroduce Postgres overlay with db service and rhdh health dependency +32/-0

Introduce Postgres overlay with db service and rhdh health dependency

• Adds a new Compose overlay that defines the 'db' PostgreSQL service and injects 'rhdh.depends_on' with 'service_healthy' semantics. Supports pinning the image via 'POSTGRES_IMAGE' while keeping a default image in the overlay.

compose-with-db.yaml

compose.postgres-upgrade.override.example.yamlAdd example override for one-time Postgres major upgrades +18/-0

Add example override for one-time Postgres major upgrades

• Introduces a documented example file users can copy to 'compose.override.yaml' to temporarily set 'POSTGRESQL_UPGRADE=copy'. Clarifies that when using multiple '-f' overlays, 'compose.override.yaml' must be explicitly included.

compose.postgres-upgrade.override.example.yaml

default.envDocument optional POSTGRES_IMAGE pin for db overlay +2/-0

Document optional POSTGRES_IMAGE pin for db overlay

• Adds commented documentation for 'POSTGRES_IMAGE' to allow users to pin the PostgreSQL image used by 'compose-with-db.yaml'. Keeps existing POSTGRES_* defaults intact.

default.env

[rhdh-qodo-merge]

Code Review by Qodo

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

1. DB admin password unset ✓ Resolved 🐞 Bug ≡ Correctness

Description

compose-with-db.yaml sets POSTGRESQL_ADMIN_PASSWORD from ${POSTGRES_PASSWORD}, but
POSTGRES_PASSWORD is only provided via env_file while ./.env is optional; if the user hasn’t
also defined POSTGRES_PASSWORD in the host env/.env at Compose render time, the db gets an empty
admin password and can fail to initialize or authenticate as expected. The same pattern is repeated
in compose.postgres-upgrade.override.example.yaml, so the upgrade flow can fail for the same
reason.

Code

compose-with-db.yaml[R21-22]

+    environment:
+      - POSTGRESQL_ADMIN_PASSWORD=${POSTGRES_PASSWORD}

Relevance

●● Moderate

Same interpolation pattern existed before, but no history discussing env_file vs ${VAR} render-time
pitfalls.

PR-#35
PR-#95

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The overlay marks .env as optional but still uses ${POSTGRES_PASSWORD} interpolation for
POSTGRESQL_ADMIN_PASSWORD, while POSTGRES_PASSWORD is only defined in default.env (an
env_file). The upgrade override repeats the same interpolation, so the upgrade path inherits the
same failure mode.

compose-with-db.yaml[16-22]
default.env[1-8]
compose.postgres-upgrade.override.example.yaml[14-18]
docs/rhdh-local-guide/postgresql-guide.md[10-22]

Agent prompt

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

## Issue description
`POSTGRESQL_ADMIN_PASSWORD` is currently set via Compose interpolation from `${POSTGRES_PASSWORD}`. This can expand to an empty string unless `POSTGRES_PASSWORD` exists in the host environment or the project `.env` at config-render time; values from a service `env_file` are not a reliable source for Compose interpolation.

## Issue Context
- `POSTGRES_PASSWORD` is defined in `default.env`, but `default.env` is only passed into containers via `env_file`.
- `./.env` is optional in the overlay.
- The Postgres image expects `POSTGRESQL_ADMIN_PASSWORD` to be set correctly.

## Fix Focus Areas
- compose-with-db.yaml[16-23]
- compose.postgres-upgrade.override.example.yaml[14-18]
- default.env[1-8]

Suggested implementation direction (pick one):
1) Add `POSTGRESQL_ADMIN_PASSWORD=...` to `default.env` (and let users override in `.env`), then remove the `environment: POSTGRESQL_ADMIN_PASSWORD=...` line from both compose files.
2) If keeping Compose interpolation, at least provide a safe default: `POSTGRESQL_ADMIN_PASSWORD=${POSTGRES_PASSWORD:-postgres}` (and ensure the upgrade override doesn’t reintroduce the empty expansion).

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

---

2. POSTGRES_IMAGE hint misleads ✓ Resolved 🐞 Bug ≡ Correctness ⭐ New

Description

default.env now suggests configuring POSTGRES_IMAGE there, but compose-with-db.yaml uses
POSTGRES_IMAGE for the service image selection (Compose-time interpolation), so changing default.env
won’t affect which db image is pulled. Users may think they pinned the DB image but will still run
the default image unless they set POSTGRES_IMAGE in .env/host env as the docs describe.

Code

default.env[R7-8]

+# Optional Postgres image for compose-with-db.yaml (default: registry.redhat.io/rhel10/postgresql-18:latest)
+# POSTGRES_IMAGE=registry.redhat.io/rhel10/postgresql-18:latest

Relevance

●●● Strong

Team often fixes misleading default.env/docs guidance; prefers telling users to override via local
.env, not tracked defaults.

PR-#40
PR-#149

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new comment in default.env introduces the misleading configuration location, while
compose-with-db.yaml consumes POSTGRES_IMAGE in the image: field and the docs explicitly direct
users to set POSTGRES_IMAGE in .env.

default.env[1-9]
compose-with-db.yaml[10-23]
docs/rhdh-local-guide/postgresql-guide.md[8-12]

Agent prompt

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

### Issue description
`default.env` contains a new commented `POSTGRES_IMAGE` example that implies the db image can be controlled from `default.env`, but `compose-with-db.yaml` selects the image via `${POSTGRES_IMAGE:-...}` which is resolved before service `env_file` is applied.

### Issue Context
Docs already instruct pinning `POSTGRES_IMAGE` in `.env`, which is the correct place for Compose-time interpolation.

### Fix Focus Areas
- default.env[7-8]

### Suggested fix
Update the comment to explicitly say `POSTGRES_IMAGE` must be set in `.env` (or exported in the shell) to affect the Compose image selection, or remove the `POSTGRES_IMAGE` hint from `default.env` entirely to avoid confusion.

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

---

3. Anonymous DB volume orphaning 🐞 Bug ☼ Reliability

Description

The db service mounts only /var/lib/pgsql/data (no named volume), which creates an anonymous
volume; when the db container is recreated, it may attach a new empty anonymous volume rather than
the previous one, making the database appear “reset” and leaving the old data stranded in an
orphaned volume. This conflicts with the upgrade docs’ assumption that recreating db will reliably
continue using the existing data volume under /var/lib/pgsql/data.

Code

compose-with-db.yaml[R14-15]

+    volumes:
+      - "/var/lib/pgsql/data"

Relevance

● Weak

Repo previously used same anonymous /var/lib/pgsql/data mount in compose.yaml db block without
change.

PR-#95
PR-#35

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The overlay defines the data mount using only a container path (anonymous volume). The upgrade guide
relies on the data staying on the mounted volume across container recreation/upgrade steps, which is
more reliable when the volume is explicitly named.

compose-with-db.yaml[13-16]
docs/rhdh-local-guide/postgresql-guide.md[102-115]
docs/rhdh-local-guide/postgresql-guide.md[132-148]

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 Postgres data directory is currently mounted using anonymous volume syntax (`- "/var/lib/pgsql/data"`). Anonymous volumes are not predictably reusable/attachable across container recreation, which is risky for persistence and for the documented major-upgrade flow.

## Issue Context
The docs instruct users to recreate the `db` container while keeping the existing data volume. That expectation is much safer when the data volume is explicitly named.

## Fix Focus Areas
- compose-with-db.yaml[13-16]
- docs/rhdh-local-guide/postgresql-guide.md[102-115]

Suggested implementation direction:
- Change the db mount to a named volume, e.g. `postgres-data:/var/lib/pgsql/data`.
- Add a top-level `volumes:` entry in the overlay (`postgres-data:`). (Compose will merge top-level volumes with `compose.yaml`.)
- Optionally update the docs to mention the named volume so users can identify it if troubleshooting.

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

---

Context sources

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

✅ Cross-repo context

Tip of the day

💡 Did you know, you can ask Qodo to dismiss a finding you disagree with, with your reason on record

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Previous reviews

Review updated until commit 18d863d

Results up to commit ff5f32d ⚖️ Balanced

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

1. DB admin password unset ✓ Resolved 🐞 Bug ≡ Correctness

Description

compose-with-db.yaml sets POSTGRESQL_ADMIN_PASSWORD from ${POSTGRES_PASSWORD}, but
POSTGRES_PASSWORD is only provided via env_file while ./.env is optional; if the user hasn’t
also defined POSTGRES_PASSWORD in the host env/.env at Compose render time, the db gets an empty
admin password and can fail to initialize or authenticate as expected. The same pattern is repeated
in compose.postgres-upgrade.override.example.yaml, so the upgrade flow can fail for the same
reason.

Code

compose-with-db.yaml[R21-22]

+    environment:
+      - POSTGRESQL_ADMIN_PASSWORD=${POSTGRES_PASSWORD}

Relevance

●● Moderate

Same interpolation pattern existed before, but no history discussing env_file vs ${VAR} render-time
pitfalls.

PR-#35
PR-#95

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The overlay marks .env as optional but still uses ${POSTGRES_PASSWORD} interpolation for
POSTGRESQL_ADMIN_PASSWORD, while POSTGRES_PASSWORD is only defined in default.env (an
env_file). The upgrade override repeats the same interpolation, so the upgrade path inherits the
same failure mode.

compose-with-db.yaml[16-22]
default.env[1-8]
compose.postgres-upgrade.override.example.yaml[14-18]
docs/rhdh-local-guide/postgresql-guide.md[10-22]

Agent prompt

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

## Issue description
`POSTGRESQL_ADMIN_PASSWORD` is currently set via Compose interpolation from `${POSTGRES_PASSWORD}`. This can expand to an empty string unless `POSTGRES_PASSWORD` exists in the host environment or the project `.env` at config-render time; values from a service `env_file` are not a reliable source for Compose interpolation.

## Issue Context
- `POSTGRES_PASSWORD` is defined in `default.env`, but `default.env` is only passed into containers via `env_file`.
- `./.env` is optional in the overlay.
- The Postgres image expects `POSTGRESQL_ADMIN_PASSWORD` to be set correctly.

## Fix Focus Areas
- compose-with-db.yaml[16-23]
- compose.postgres-upgrade.override.example.yaml[14-18]
- default.env[1-8]

Suggested implementation direction (pick one):
1) Add `POSTGRESQL_ADMIN_PASSWORD=...` to `default.env` (and let users override in `.env`), then remove the `environment: POSTGRESQL_ADMIN_PASSWORD=...` line from both compose files.
2) If keeping Compose interpolation, at least provide a safe default: `POSTGRESQL_ADMIN_PASSWORD=${POSTGRES_PASSWORD:-postgres}` (and ensure the upgrade override doesn’t reintroduce the empty expansion).

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

---

2. Anonymous DB volume orphaning 🐞 Bug ☼ Reliability

Description

The db service mounts only /var/lib/pgsql/data (no named volume), which creates an anonymous
volume; when the db container is recreated, it may attach a new empty anonymous volume rather than
the previous one, making the database appear “reset” and leaving the old data stranded in an
orphaned volume. This conflicts with the upgrade docs’ assumption that recreating db will reliably
continue using the existing data volume under /var/lib/pgsql/data.

Code

compose-with-db.yaml[R14-15]

+    volumes:
+      - "/var/lib/pgsql/data"

Relevance

● Weak

Repo previously used same anonymous /var/lib/pgsql/data mount in compose.yaml db block without
change.

PR-#95
PR-#35

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The overlay defines the data mount using only a container path (anonymous volume). The upgrade guide
relies on the data staying on the mounted volume across container recreation/upgrade steps, which is
more reliable when the volume is explicitly named.

compose-with-db.yaml[13-16]
docs/rhdh-local-guide/postgresql-guide.md[102-115]
docs/rhdh-local-guide/postgresql-guide.md[132-148]

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 Postgres data directory is currently mounted using anonymous volume syntax (`- "/var/lib/pgsql/data"`). Anonymous volumes are not predictably reusable/attachable across container recreation, which is risky for persistence and for the documented major-upgrade flow.

## Issue Context
The docs instruct users to recreate the `db` container while keeping the existing data volume. That expectation is much safer when the data volume is explicitly named.

## Fix Focus Areas
- compose-with-db.yaml[13-16]
- docs/rhdh-local-guide/postgresql-guide.md[102-115]

Suggested implementation direction:
- Change the db mount to a named volume, e.g. `postgres-data:/var/lib/pgsql/data`.
- Add a top-level `volumes:` entry in the overlay (`postgres-data:`). (Compose will merge top-level volumes with `compose.yaml`.)
- Optionally update the docs to mention the named volume so users can identify it if troubleshooting.

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

---

[zdrapela]

Stack retargeted to dev (stack #286): #278 (base dev) → #276. Pre-rebase backups on fork: backup/2026-08-04-docs-pg16-to-pg18-upgrade / backup/2026-08-04-fix-RHDHBUGS-1865-compose-with-db.

[rhdh-qodo-merge]

Code review by qodo was updated up to the latest commit ef01709

[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