Keycloak - Tuning Database Settings when experiencing Transaction timeouts

September 29, 2023

Tags: #keycloak #database #transaction #timeout

When you want to update your KEYCLOAK deployment to the most recent version, Keycloak normally takes control also over database migration. Schema and data is automatically migrated or converted to meet the actual requirements.

In case you have a large amount of data, this migration might fail due to a timeout. This is, because the underlying Arjuna framework for transaction management has a default timeout of 5 minutes configured. Very large datasets might need more time to be migrated.

You can “tune” (adjust to your requirements) this setting with this configuration parameter, e.g. in the JAVA_OTPS (or JAVA_OPTS_APPEND) environment variable of your deployment with:

-Dquarkus.transaction-manager.default-transaction-timeout=3600

Now, with this setting from the example above, the default transaction timeout for database transactions will be 1 hour (3600 seconds).

But be careful! This setting is not only for the database migration when updating Keycloak, it is a global setting and valid for all database transactions, also during uptime of Keycloak!

Additionally, you can also fine-tune the use of batch-sizes, with which the database migration will happen. This might also save you a lot of time, as more than one record will be processed/updated at once:

-Dkeycloak.migration.batch-enabled=true
-Dkeycloak.migration.batch-size=1000

This is for your convenience.
Use it at your own risk and responsibility!

« Keycloak Events Logging Revised Keycloak - Calling Required Actions directly »