fix(helm): infer Keycloak DB driver from external database URL

[sebastianiv21]

Description

Fixes https://linear.app/appsmith/issue/APP-15798

With postgresql.enabled: false and a user-supplied applicationConfig.APPSMITH_KEYCLOAK_DB_URL, the ConfigMap resolved APPSMITH_KEYCLOAK_DB_DRIVER to h2 — the ternary keys off the subchart flag, not the URL. The container entrypoint only reads the Keycloak DB URL when the driver is postgresql, so Keycloak silently persisted all SSO data (realms, users, OIDC/SAML clients, sessions) to a local H2 file inside the pod, while Temporal and the AI DB did use the external PostgreSQL. The deployment looks healthy but the externalization is partial: SSO data is lost on pod restart, and each HA replica would have its own H2 file.

This is the path of the careful user — following the external PostgreSQL guide and correctly disabling the bundled subchart is exactly what triggers it.

Fix

Treat a non-empty APPSMITH_KEYCLOAK_DB_URL as PostgreSQL regardless of the subchart flag:

postgresql.enabled	External URL set	Driver before	Driver after
true	no	postgresql	postgresql (unchanged)
true	yes	postgresql	postgresql (unchanged)
false	yes	h2 ⚠️	postgresql ✅
false	no	h2	key omitted — the container entrypoint decides at runtime

An explicitly set APPSMITH_KEYCLOAK_DB_DRIVER is honored unchanged in all cases.

The last row covers URLs supplied through secretName / secrets / externalSecrets, which this template cannot inspect: instead of pinning h2, the chart leaves the key unset so the entrypoint can infer the driver from the final resolved environment (the same presence-based pattern Temporal and RTS already use with this variable). A companion EE entrypoint PR adds that inference; with an older image, an absent driver falls back to dev-file — identical to the previous explicit h2 — so no chart/image ordering is required.

Upgrade note

Deployments in the fixed cohort (postgresql.enabled: false, external URL set, driver unset) switch Keycloak from pod-local H2 to the external PostgreSQL on upgrade. Keycloak bootstraps a fresh schema there — state accumulated in the local H2 file (realms, users, clients) does not migrate. That state was already ephemeral (lost on every pod reschedule), which is what this fix addresses. Two related behavior changes:

• If the external URL is unreachable or has wrong credentials, Keycloak now fails at startup instead of silently "working" on H2 — fail-loud is intentional.
• Setting APPSMITH_KEYCLOAK_DB_DRIVER explicitly bypasses the inference entirely, and is the escape hatch for anyone who wants the old behavior.

Validation

• helm unittest: 96 tests / 20 suites / 11 snapshots green, including a new tests/keycloak_db_driver_test.yaml covering the four rows of the matrix above; chart-version snapshots regenerated for 3.9.1.
• Live repro on a kind cluster against an external PostgreSQL 16 (chart v2.2 image): before the fix, Keycloak boots with jdbc-h2 / KC_DB=dev-file and creates zero tables in the external database; with driver postgresql, Keycloak creates its ~94 tables there. Temporal/AI DB used the external URL in both cases.
• helm lint passes.

Automation

/ok-to-test tags="@tag.Sanity"

🔍 Cypress test results

Tip

🟢 🟢 🟢 All cypress tests have passed! 🎉 🎉 🎉
Workflow run: https://github.com/appsmithorg/appsmith/actions/runs/31744829943
Commit: c90ebf2
Cypress dashboard.
Tags: @tag.Sanity
Spec:

---

Thu, 13 Aug 2026 21:47:38 UTC

Communication

Should the DevRel and Marketing teams inform users about this change?

• Yes
• No

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved Keycloak database driver detection for PostgreSQL and externally configured database URLs.
  • Prevented unnecessary driver configuration when the database type can be inferred automatically.
  • Preserved explicitly configured database drivers.

• Chores

  • Updated the Helm chart version to 3.9.1.

[coderabbitai]

Walkthrough

The Helm chart now emits the Keycloak PostgreSQL driver only when PostgreSQL configuration is detected. Helm tests cover default, omitted, and explicit driver cases. The chart version increases to 3.9.1.

Changes

Keycloak driver configuration

Layer / File(s)	Summary
Conditional driver emission and validation deploy/helm/templates/configMap.yaml, deploy/helm/tests/keycloak_db_driver_test.yaml, deploy/helm/Chart.yaml	The template emits postgresql for bundled or external PostgreSQL configuration, omits the key when no signal exists, and preserves explicit drivers. Helm tests cover these cases. The chart version is 3.9.1.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: amelia-c0n

Poem

PostgreSQL waits in the chart,
Appearing when its signals start.
Explicit drivers hold their place,
Missing keys leave inference space.
Tests keep each path in sight.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the main Helm fix: inferring the Keycloak database driver from an external database URL.
Description check	✅ Passed	The description includes the required sections and provides clear motivation, implementation details, upgrade impact, testing results, automation status, and communication choice.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/helm-keycloak-driver-external-pg

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

deploy/helm/tests/keycloak_db_driver_test.yaml (1)

38-48: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use a non-default explicit driver in this test.

postgresql is also the inferred value. This test passes if the template overwrites an explicit driver with the default. Set APPSMITH_KEYCLOAK_DB_DRIVER and the expected value to dev-file to verify that explicit values remain unchanged.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@deploy/helm/tests/keycloak_db_driver_test.yaml` around lines 38 - 48, Update
the test case “explicitly set driver is honored unchanged” to set
APPSMITH_KEYCLOAK_DB_DRIVER to dev-file and assert that
data.APPSMITH_KEYCLOAK_DB_DRIVER equals dev-file, while preserving the disabled
PostgreSQL configuration and external database URL.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@deploy/helm/tests/keycloak_db_driver_test.yaml`:
- Around line 38-48: Update the test case “explicitly set driver is honored
unchanged” to set APPSMITH_KEYCLOAK_DB_DRIVER to dev-file and assert that
data.APPSMITH_KEYCLOAK_DB_DRIVER equals dev-file, while preserving the disabled
PostgreSQL configuration and external database URL.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d1fa85da-b33f-4605-9837-4fb9f2d60ed6

📥 Commits

Reviewing files that changed from the base of the PR and between 6140803 and 7532daf.

⛔ Files ignored due to path filters (1)

• deploy/helm/tests/__snapshot__/defaults_snapshot_test.yaml.snap is excluded by !**/*.snap

📒 Files selected for processing (3)

• deploy/helm/Chart.yaml
• deploy/helm/templates/configMap.yaml
• deploy/helm/tests/keycloak_db_driver_test.yaml

[linear-code]

APP-15798