Hello Keycloak team,

I’m currently working on a thesis project where I’m implementing a custom Keycloak storage provider with YDB as the primary datastore (using Storage SPI). At the moment, I’m re-implementing the Realm model (RealmModel, RealmProvider and RealmProviderFactory).
And I’d like to better understand the design decisions behind Keycloak’s data model.

In particular, I’m interested in how you decide:

• which properties of an entity (e.g. RealmModel) are stored as explicit columns in the main tables (like ACCESS_CODE_LIFESPAN, ADMIN_THEME, SSL_REQUIRED, etc.)
• another table, like REALM_REQUIRED_CREDENTIAL
• and which ones are stored in separate attributes tables(like WEBAUTHN_POLICY, DISPLAY_NAME, etc.)

I’d really appreciate your insights on the following points:

Design criteria

What were the main factors when deciding whether a field should be?

Was it because of frequency of access? participation in queries/filters? backward compatibility? extensibility? schema evolution concerns?

Concrete examples

Are there any concrete examples from the Realm (or User/Client) model where this trade-off was discussed explicitly?

For instance, fields that:

• started as attributes and later became core fields (or vice versa),
• or were intentionally left as attributes despite frequent usage.

Performance and testing

Did you perform any performance or load testing to evaluate:

• access patterns to attributes vs core columns,
• impact on startup time, authentication flows, or admin queries,
• or scalability concerns related to large numbers of attributes?

If yes, were these tests part of internal benchmarks or real-world feedback from large installations?

The reason I’m asking is that when mapping Keycloak’s model to a different backend (in my case, YDB with a different storage and indexing model), this distinction has a significant impact on schema design, indexing strategy, and query performance.

Any guidance, rationale, or references to past discussions would be extremely helpful.

Thanks a lot for your work on Keycloak and for your time!