Chapter 2. Upgrading the Red Hat build of Keycloak server
2.1. Preparing for upgrading
Procedure
- Back up the old installation, such as configuration, themes, and so on.
Back up the database using instructions in the documentation for your relational database.
The database will no longer be compatible with the old server after the upgrade. If you need to revert the upgrade, first restore the old installation, and then restore the database from the backup copy.
- Handle any open transactions and delete the data/tx-object-store/ transaction directory.
In a minor upgrade of Red Hat build of Keycloak, all user sessions are lost. After the upgrade, all users will have to log in again.
2.2. Downloading the server ZIP file
Procedure
- Download Red Hat build of Keycloak from the Red Hat website and extract it.
- Move the ZIP file to the desired location.
Extract the archive.
After extracting this file, you should have a directory that is named rhbk-22.0.11.
-
Copy
conf/,providers/andthemes/from the previous installation to the new installation.
2.3. Database migration
Red Hat build of Keycloak can automatically migrate the database schema, or you can choose to do it manually. By default, the database is automatically migrated when you start the new installation for the first time.
2.3.1. Automatic relational database migration
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
2.3.2. Manual relational database migration
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
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>
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.
