8000 Document PgBouncer failover behavior in the DB guide by buketcoban · Pull Request #53355 · keycloak/keycloak · GitHub
[go: up one dir, main page]
Skip to content

Document PgBouncer failover behavior in the DB guide #53355

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ahus1 merged 2 commits into from
Sep 30, 2026
Merged

Document PgBouncer failover behavior in the DB guide #53355

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
16d60b9
Document PgBouncer failover behavior in the DB guide
buketcoban Sep 30, 2026
fb15a43
Review
ahus1 Sep 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/guides/server/db.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,6 +317,22 @@ You can override this behavior by setting your own value for `targetServerType`
The `targetServerType` is only applied automatically to the primary datasource, as requirements might be different for additional datasources.
====

==== Using PgBouncer

When {project_name} connects to PostgreSQL through PgBouncer, connections can fail after a failover or switchover.
PgBouncer caches the `in_hot_standby` value it reports to new client connections, and it can keep reporting `in_hot_standby=on` after the switch.
Because `targetServerType` is set to `primary`, the PostgreSQL JDBC driver then treats the connection as a reader instance and refuses it with the error `Could not find a server with specified targetServerType: primary`.

This is a known PgBouncer issue, tracked in https://github.com/pgbouncer/pgbouncer/issues/859[pgbouncer/pgbouncer#859].
Reloading PgBouncer after a failover or switchover makes it report the current value again.

Setting `targetServerType` to `any` avoids the error, but it also removes the protection described above, so {project_name} might connect to a reader instance.
Only use it if your routing in PgBouncer se 625D nds database connections exclusively to the writable primary database.

Set `targetServerType=any` via `db-url-properties`:

<@kc.start parameters="--db postgres --db-url-properties='?targetServerType=any'"/>

=== Permissions of the database user

Ensure that the database user has `SELECT` permissions to the following tables to ensure an efficient upgrade: `pg_class`, `pg_namespace`.
Expand Down
Loading
0