Upgrading Keycloak: what the database migration does, and when a rolling upgrade breaks

Short answer: upgrading Keycloak is mostly a database migration that runs automatically when the new version starts. The risk is not the download; it is a schema change against a production database, a custom extension that no longer loads, or a rolling upgrade across nodes that do not agree on the new behavior. Read the upgrading guide for the versions you are crossing, take a database snapshot, test on a copy, and only then touch production.

Keycloak's client libraries are released independently, so "upgrade Keycloak" and "upgrade the adapters" are two separate tasks. The latest client libraries are expected to work with the latest server; older applications may need their own compatibility check.

Before you start

1. Read the upgrading guide for every version you cross, not just the target version. It lists the changes that might require configuration or application changes.
2. Check your extensions and themes. Custom providers built against Keycloak internals are the most common upgrade failure. In 26.8, Keycloak moved to Quarkus 3.40 from 3.33, and extensions that depend on Quarkus internals have to be retested.
3. Snapshot the database. The automatic migration is not a reason to skip a backup; it is the reason you need one.
4. Run the upgrade on a copy first. Point a staging Keycloak at a restored copy of the production database and start it with the target version. Fix what breaks there.
5. Check the Java runtime. Build and run the target version on a supported JDK, and keep the container image and the JDK aligned.

What happens on startup

Keycloak migrates the relational schema automatically when the new version starts against an existing database. The server detects the schema version, applies the changesets and then serves traffic.

For large tables, Keycloak may skip index creation during the automatic migration and log the SQL statement instead. After startup, on supported databases, it creates the missing index in the background. That keeps the upgrade window shorter, but it means performance can be uneven until the index exists. On a very large user or event table, watch the database during the first hours after the upgrade rather than assuming it is finished when the login page responds.

If the migration fails, the server does not start cleanly. Do not restart it repeatedly against the same database while you guess; restore the snapshot, read the error, and fix the cause in staging.

Manual and validate strategies

Some teams need to control the SQL. Keycloak supports migration strategies beyond automatic:

• manual logs the SQL and does not apply it, so a database administrator can run it.
• validate checks the schema and fails if it does not match, without making changes.

Manual migration is common in regulated environments where schema changes go through a review. It is not easier: you now own the ordering and the rollback. If custom JPA entity providers are in use, the export used for manual migration includes their changesets, so the scripts contain the changes those providers need.

Choose a strategy deliberately and document it. A database that was migrated manually once but runs automatic migration later is a recipe for a schema that nobody can reason about.

Rolling upgrades: when they are not safe

A rolling upgrade replaces nodes one at a time while the cluster keeps serving traffic. Keycloak supports it for many releases, but not all, and the exceptions are the ones that hurt.

The upgrading guide calls out specific changes where older and newer nodes cannot coexist safely. In 26.8, for example:

• a new Dynamic Client Registration policy provider that older 26.8.x nodes do not understand, where the guide says a rolling upgrade is not supported and the cluster should be shut down and upgraded together;
• an Admin API audience check that makes admin tokens issued by older nodes fail with 401 on upgraded nodes;
• logout session notes that older nodes do not write, so an in-flight logout can restart or miss a redirect.

The safe default is: if the upgrading guide does not explicitly say the release supports rolling upgrades, take the cluster down, upgrade all nodes, and bring it back. A short maintenance window is cheaper than debugging a mixed-version cluster.

Changes worth knowing in recent releases

The upgrading guide is long because every release changes behavior. A few themes recur:

• Features move from preview to supported. The stateless feature is the direction for deployments that want fewer in-memory sessions; the older clusterless feature is being removed in a future release.
• Login failure storage changed. The login-failures:v1 feature restores the old in-memory behavior and is incompatible with stateless mode.
• Security defaults tighten. SCIM and client secret rotation became enabled by default, so their old feature flags are no longer needed. The Admin API audience check is on by default, and disabling it is explicitly discouraged.
• SAML edge cases have switches. SAML 1.1 parsing and larger SAML SOAP messages are behind explicit options, for integrations that still need them.

Read the list for your target version, not a summary from a blog. The guide is the authority.

Upgrade checklist

• Read the upgrading guide for each version crossed.
• List every custom provider, theme, mapper and client library in use.
• Rebuild custom providers against the target version and test them.
• Restore a production database copy into staging.
• Start the target Keycloak against the copy and fix failures.
• Check the health endpoints, the discovery document and a real login.
• Take a production database snapshot and record the restore command.
• Decide between rolling and full-cluster maintenance from the guide.
• Upgrade all nodes to the same version; do not leave a mixed cluster longer than the guide allows.
• Watch the database, login latency and error rates for the first hours.
• Keep the previous image and the snapshot until the new version has run for a full business cycle.

Rollback

The honest answer is that rollback is a database restore, not a downgrade. Keycloak does not promise that an older server can run against a schema migrated by a newer one. If the upgrade fails, restore the snapshot and the previous image together. That is why the snapshot and the image tag are part of the upgrade, not an afterthought.

When the upgrade is the reason to leave

Upgrades are manageable when you run one cluster. They become a program when you run many instances, with custom themes, providers and client libraries, and each one needs a staging rehearsal. That is the point where a managed instance or a simpler platform starts to pay for itself. Casdoor handles schema upgrades as part of the release and a managed instance is upgraded by us; the flat-price plans are on the pricing page. For the hosting trade-offs, see managed Keycloak hosting.

FAQ

Does Keycloak upgrade the database automatically? Yes. The relational schema migration runs automatically at startup. Large tables may have index creation deferred and logged, and the server creates the index in the background after startup on supported databases.

Can I skip versions? Do not assume it. Read the upgrading guide for every version you cross and test the jump on a database copy. The guide is written per release, and behavior changes accumulate.

Are rolling upgrades supported? For many releases, yes. For changes that older nodes cannot understand, the guide says a rolling upgrade is not supported and the cluster must be upgraded together. Check the target release before scheduling.

Can I downgrade if the upgrade fails? Treat rollback as restoring the database snapshot and the previous image. Running an older Keycloak against a newer schema is not a supported downgrade path.

Do client libraries upgrade with the server? No. Keycloak client libraries are released independently. Check the library version your applications use, especially if they implement OIDC or SAML themselves.