Problem statement

The current JPA map storage implementation has one field entityVersion that identifies the schema version. This identifies (a) the format the JSON has been written in and (a) might show how and if some additional search columns/tables have been filled.

The JSON is migrated on read, and when the entity is updated the entity version is updated to the current entity version from the perspective of the now running Keycloak version. It also ensures that it only reads entity versions that are the current supported version +1; it will fail with a IllegalArgumentException on any higher version (see JpaEntityMigration).

This sums up as:

• write entities with the current entity version to the database
• read any entity version from the DB that is smaller or equal to the current plus one

This could fail in the following way:

• read a version of the next version (N+1) that has additional fields in the JSON.
• JsonbType will ignore any additional field
• after an update has been made, the entity will be written to the database with the JSON format for version (N), and the new fields will be lost.
• The current implementation will keep the entity version (N+1) so there will be no way to determine that the fields have been removed or a migration needs to be implemented.

This could also fail in ways that a additional fields are not updated by the (N) Keycloak version what would need to be updated by a (N+1) entity version.

How to update an entity that has been written to the database with a (N+1) version is not handled in the concept document here: https://github.com/keycloak/keycloak-community/blob/main/design/keycloak.x/storage-persistence.md

Approach

• Apply a defensive programming style to throw an exception when attempting to write an entity that has a newer version in the database.
• Rework repetitive calls to checkEntityVersionForUpdate() in JpaClientEntity to a method annotated with @PreUpdate and @PrePersist, so that is called whenever a SQL insert or update is triggered.

Out of scope / future task: In a no-downtime scenario write access could be redirected only to the new versions of Keycloak (assuming a green-blue-deployment scenario).

Benefits

• Ensuring that only consistent data, and newer fields from later versions are not removed.
• Simple approach to make the existing implementation safe to not write old format JSON to a new entity version database row
• Simplify the update of the entity version by not calling checkEntityVersionForUpdate() in multiple places.
• Leave the more complicated approach of a hierarchical version number for a future date where a practical example is at hand.

Alternatives

• Leave it "as is".
• Discuss how a hierarchical version number could be implemented now - a practical example would be required.