Chapter 2. Upgrading the Red Hat build of Keycloak server

To perform an automatic migration, start the server connected to the desired database. If the database schema has changed for the new version of the server, it will be migrated.

Creating an index on huge tables with millions of records can be very time-consuming and possibly cause a major service disruption. Therefore, a threshold exists to limit the number of records allowed for the index. A warning message appears in the server logs with SQL commands you can apply later manually.

To change the threshold, set the index-creation-threshold property, value for the default connections-liquibase provider:

kc.[sh|bat] start --spi-connections-liquibase-default-index-creation-threshold=300000

kc.[sh|bat] start --spi-connections-liquibase-default-index-creation-threshold=300000

To enable manual upgrading of the database schema, set the migration-strategy property value to "manual" for the default connections-jpa provider:

kc.[sh|bat] start --spi-connections-jpa-legacy-migration-strategy=manual

kc.[sh|bat] start --spi-connections-jpa-legacy-migration-strategy=manual

When you start the server with this configuration, the server checks if the database needs to be migrated. The required changes are written to the bin/keycloak-database-update.sql SQL file that you can review and manually run against the database.

If you want to change the path and name of the exported SQL file, set the migration-export property for the default connections-jpa provider:

kc.[sh|bat] start --spi-connections-jpa-legacy-migration-export=<path>/<file.sql>

kc.[sh|bat] start --spi-connections-jpa-legacy-migration-export=<path>/<file.sql>

For more details on applying this file to the database, see the documentation for your relational database. After the changes have been written to the file, the server exits.