Keycloak Upgrade 26.7.x to 26.8.x #55008

cgurtshaw · 2026-11-10T17:30:38Z

cgurtshaw
Nov 10, 2026

PR #52401 ("Multi-IdP for orgs: Data Model") moves org↔IdP linking from a single IDENTITY_PROVIDER.ORGANIZATION_ID column to a many-to-many ORG_IDENTITY_PROVIDER join table. The data migration (JpaUpdate26_8_0_DomainIdpRoutingMigration) is additive and looks correct, but the final changeset in the same file, 26.8.0-drop-idp-organization-id in model/jpa/src/main/resources/META-INF/jpa-changelog-26.8.0.xml, drops the column outright:

 <changeSet author="keycloak" id="26.8.0-drop-idp-organization-id">
     <dropIndex tableName="IDENTITY_PROVIDER" indexName="IDX_IDP_REALM_ORG"/>
     <dropIndex tableName="IDENTITY_PROVIDER" indexName="IDX_IDP_FOR_LOGIN"/>
     <dropColumn tableName="IDENTITY_PROVIDER" columnName="ORGANIZATION_ID"/>
     ...
 </changeSet>

The IdentityProviderEntity in 26.7.x maps that column as a plain eager @Column field, so Hibernate includes it in the generated SELECT for every IdentityProviderEntity load. As a result, the instant a 26.8.0+ node runs this migration against a DB that any 26.7.x node is still connected to, every identity-provider read on that 26.7.x node starts failing, including normal (non-org) brokered logins.

Reproduction
Minimal repro, no custom extensions involved:

Start Keycloak 26.7.2 against a fresh Postgres DB, create a plain OIDC identity provider.
Start Keycloak 26.8.1 against the same DB (no restart of the 26.7.2 node). Startup logs show the migration running (Migrating older model to 26.8.0).
On the still-running 26.7.2 node, trigger a real login via kc_idp_hint= (after the realm cache naturally reloads/evicts — e.g. via POST /admin/realms/{realm}/clear-realm-cache, simulating normal cache turnover). The login fails with the built-in error page ("Unexpected error when handling authentication request to identity provider"), and the server log shows:

org.keycloak.models.ModelException: Database operation failed
Caused by: org.postgresql.util.PSQLException: ERROR: column ipe1_0.organization_id does not exist at org.keycloak.models.jpa.JpaIdentityProviderStorageProvider.getEntityById(JpaIdentityProviderStorageProvider.java:518)

This means any deployment that does a linear/rolling traffic shift, or any form of blue-green cutover where old and new versions can briefly share the same database, has a hard outage window the moment the new version's migration runs — with no way to roll the application back out of it (the schema change isn't undone by reverting app versions).

Questions

Was this intentional? i.e., is a full offline/maintenance-window cutover the expected and only supported path across the 26.7.x → 26.8.x boundary, with in-place/rolling upgrades explicitly unsupported for this release?
If not intentional: would the project consider an expand/contract split for migrations like this going forward? i.e., land the additive schema changes and data migration in one release, and defer the actual dropColumn/dropIndex to a later release once no supported upgrade path can run the two versions concurrently? In this specific case it looks like the fix would have been as simple as moving the 26.8.0-drop-idp-organization-id changeset into the next version's changelog, since 26.8.0's own entity mapping already stops reading that column.
Is there existing guidance (anywhere in CONTRIBUTING.md or the upgrade guide) for contributors on how destructive schema changes to core, frequently-read tables should be sequenced across releases? If not, would a written guideline here be welcome, to help reviewers catch this class of issue earlier?

Drako01 · 2026-11-11T20:24:01Z

Drako01
Nov 11, 2026

For question 1, the documented upgrade contract requires stopping the old nodes across this boundary:
26.7 to 26.8 is a minor-version upgrade, rather than a patch upgrade within one major.minor stream.

The 26.8.0 upgrading guide
explicitly says to stop Keycloak for minor/major upgrades and to stop all old-version nodes before
migrating the database. It also states that the upgraded schema need not remain compatible with the
old server and that database changes cannot be rolled back by reverting the application image.
Recovery requires the previous installation and its database backup.

By comparison, the update-compatibility guide
describes zero-downtime version upgrades for patch releases within the same major.minor stream.
That does not establish compatibility between 26.7.x and 26.8.x.

Consequently, briefly overlapping old/new nodes against that database is outside the documented
upgrade procedure. Blue-green traffic switching alone does not remove the database compatibility
requirement.

Your expand/contract proposal is still a reasonable architectural discussion, but moving one
changeset would not by itself establish that other schema, cache and protocol changes support
mixed-minor operation. That needs an explicit compatibility contract and corresponding upgrade tests.

For questions 2-3, only maintainers can confirm whether they want that guarantee or a contributor
guideline. The contribution guide
recommends discussing larger changes first. I have not executed your reproduction or confirmed the
intent behind that changeset.

0 replies

AZapata27 · 2026-11-12T02:35:05Z

AZapata27
Nov 12, 2026

Adding a few things to the above, mostly for (3) and for the cutover itself.

The rule isn't only in the docs. kc.sh update-compatibility check reports a rolling update only when both versions share major.minor and the target micro is the same or newer (KeycloakCompatibilityMetadataProvider). The Operator's Auto strategy relies on that check, so 26.7 → 26.8 always comes out as a recreate.

What the build does guard is patch releases. Release branches carry rolling-upgrades-supported-changes.json and rolling-upgrades-unsupported-changes.json in model/jpa, and the db-compatibility-verifier fails the build when a new changeset isn't classified in one of them. That's the closest thing to a schema compatibility policy today, and it only covers 26.8.x → 26.8.y. The contributor doc on schema changes (docs/updating-database-schema.md) explains how to add and test a changeset, but has nothing on sequencing destructive ones. So for (3), there's no written guidance yet.

For the blue/green itself, you can keep the new nodes from migrating on startup. With --spi-connections-jpa--quarkus--migration-strategy=manual plus --spi-connections-jpa--quarkus--migration-export=<file>, Keycloak writes the SQL to a file instead of applying it (db guide). Then the schema change happens when you decide: stop the 26.7 nodes, apply the SQL, start 26.8 and switch traffic. It's still a short outage, but it won't hit you in the middle of the traffic shift.

0 replies

Navigation Menu

Repository navigation

Keycloak Upgrade 26.7.x to 26.8.x #55008

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Keycloak Upgrade 26.7.x to 26.8.x #55008

Uh oh!

cgurtshaw Nov 10, 2026

Replies: 2 comments

Uh oh!

Drako01 Nov 11, 2026

Uh oh!

AZapata27 Nov 12, 2026

cgurtshaw
Nov 10, 2026

Drako01
Nov 11, 2026

AZapata27
Nov 12, 2026