Repository navigation
Document PgBouncer failover behavior in the DB guide - #53355
Conversation
Closes keycloak#49515 Signed-off-by: Buket Çoban <100703834+buketcoban@users.noreply.github.com>
There was a problem hiding this comment.
Copilot review overview
🟢 Approval recommended
The documentation accurately addresses the reported failure mode and clearly warns about the mitigation’s routing requirements.
Review effort: Balanced
Findings: None
What changed in this PR
Documents PgBouncer’s stale in_hot_standby behavior during PostgreSQL failovers.
Changes:
- Explains the resulting JDBC connection failure.
- Documents PgBouncer reload and
targetServerType=anymitigations and risks. - Links the upstream PgBouncer issue.
| File | Description |
|---|---|
docs/guides/server/db.adoc |
Adds PgBouncer failover guidance. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
@nils-jakobs / @atiqur-rahman-pro / @Cojacfar - can one of you please review the pull request and confirm that this is correct? Thanks! |
|
Thanks for adding this documentation, @buketcoban! The explanation accurately describes the issue: PgBouncer caching stale The trade-offs and risks of setting Looks good to me! @ahus1 |
|
@atiqur-rahman-pro - are you running this setup in production? If not, I would wait a bit more for someone who does. |
|
No, I'm not running this setup in production myself। My review was based on verifying the pgjdbc driver behavior, Keycloak configuration syntax, and the upstream PgBouncer mechanics discussed in #49515. Waiting for hands-on confirmation from someone running it in production (like @nils-jakobs or @Cojacfar) definitely makes sense! |
|
I've had this change live in my (relatively small) production environment for quite a while without issue now. I'm running Keycloak so it's in a Docker container and passing the ?targetServerType=any through KC_DB_URL. For context, I'm using HAProxy to determine which backend Patroni node is active. So my DB_URL is going to a LB and is always routed to the actual primary and not a read-only instance. Your change seems correct in my reading! |
|
Thanks @ahus1 for the review and the improvements, and @atiqur-rahman-pro and @Cojacfar for confirming! |
|
@buketcoban - thank you for the PR. For future PRs, it would be good to know if you add documentation if you've tested it with a local setup as a developer, if you are describing a setup you used in your production environment, or if you derived it from documentation. As a follow-up: it would be interesting to know for me (as a Keycloak maintainer and developer, but someone who never ran Keycloak in production):
|
|
I've created a follow-up issue #53452 to continue the discussion, and also extend it to AWS RDS Proxy. My current gut-feeling: Don't use a DB proxy for Keycloak, instead size your connection pool on each instance. |
Adds a sub-paragraph under "Writer and reader instances" in the DB guide that describes how PgBouncer can keep reporting a stale
in_hot_standbyvalue after a failover or switchover, and links the upstream PgBouncer issue pgbouncer/pgbouncer#859, as requested in #49515.This change was drafted with the help of an AI assistant. I reviewed every line and can explain and revise it.
Closes #49515