Before reporting an issue

[x] I have read and understood the above terms for submitting issues, and I understand that my issue may be closed without action if I do not follow them.

Area

storage

Describe the bug

When performing a Keycloak upgrade from versions ≤ 22.0.4 directly to 26.2.x, the startup fails with a Liquibase checksum validation error:
`
Validation Failed:

 1 changesets check sum
      META-INF/jpa-changelog-2.5.0.xml::2.5.0-unicode-oracle::hmlnarik@redhat.com 

was: 8:8b6fd445958882efe55deb26fc541a7b but is now: 8:6be40845dcc4adb4512f70ce19c71dfd
`

Version

26.2.0

Regression

[x] The issue is a regression

Expected behavior

When performing a Keycloak upgrade from versions ≤ 22.0.4 directly to 26.2.x, the startup and db migration passed without any issues.

Actual behavior

When performing a Keycloak upgrade from versions ≤ 22.0.4 directly to 26.2.x, the startup fails with a Liquibase checksum validation error:
`
Validation Failed:

 1 changesets check sum
      META-INF/jpa-changelog-2.5.0.xml::2.5.0-unicode-oracle::hmlnarik@redhat.com 

was: 8:8b6fd445958882efe55deb26fc541a7b but is now: 8:6be40845dcc4adb4512f70ce19c71dfd

How to Reproduce?

• Start with Keycloak 22.0.4 or lower
• Run keycloak to initialize the DB (DATABASECHANGELOG will contain 8: checksums).
• Upgrade Keycloak to 26.2.0 to run db migration
• Start Keycloak, observe migration failure.

Anything else?

Cause

In versions of Keycloak up to 22.0.4, Liquibase used version 4.20.0 (and lower), which generated 8: prefixed checksums.
Starting from Keycloak 22.0.5, Liquibase was updated to 4.23.2, which defaults to 9: prefixed checksums.
In Keycloak 26.2.x, changelogs now explicitly contain only the new 9: checksums and 7:checksums.
This leads to checksum mismatch errors when upgrading from older versions directly to 26.2.x, as the existing database has 8: checksums, but the changelogs expect 9:.

Impacted upgrade paths

From Keycloak version | To Keycloak version | Result
17.x, 20.x, 21.x, 22.0.0 - 22.0.4 | 26.1.x | ✅ OK (still uses 8: checksums)
17.x, 20.x, 21.x, 22.0.0 - 22.0.4 | 26.2.0 | ❌ Fails due to checksum mismatch
22.0.5 - 26.1.x | 26.2.0 | ✅ OK (DB: 9:, changelog: 9

Suggested resolution

To ensure smoother upgrades, consider one of the following:
✅ Add the older checksums (8 as valid in changelogs for compatibility.
✅ Document a required intermediate upgrade path (for example, to 22.0.5 or 26.1.x first before going to 26.2.x).

Related Keycloak changes (Root cause)

PR #38601 (https://github.com/keycloak/keycloak/pull/38601) (Changelog update to 9: checksums)