From e999186b845fd04b4027fbd7b24510dd4251f59e Mon Sep 17 00:00:00 2001 From: Alexander Schwartz Date: Fri, 14 Oct 2022 18:40:53 +0200 Subject: [PATCH] Add H2 upgrade to release notes and migration guide Relates to keycloak/keycloak#12607 Relates to keycloak/keycloak#11292 Relates to keycloak/keycloak#10113 Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com> --- release_notes/topics/20_0_0.adoc | 9 +++++- upgrading/topics/keycloak/changes-20_0_0.adoc | 29 ++++++++++++++++++- 2 files changed, 36 insertions(+), 2 deletions(-) diff --git a/release_notes/topics/20_0_0.adoc b/release_notes/topics/20_0_0.adoc index f334fdcb50..2af1a20e2e 100644 --- a/release_notes/topics/20_0_0.adoc +++ b/release_notes/topics/20_0_0.adoc @@ -9,4 +9,11 @@ More details can be found at the https://www.keycloak.org/server/hostname[Config = Improvements to `kc.bat` when running Keycloak on Windows -In this release, we are making important changes to `kc.bat` in order to give the same experience as when running on Linux. \ No newline at end of file +In this release, we are making important changes to `kc.bat` to give the same experience as when running on Linux. + += Upgrade of embedded H2 database + +{project_name} ships for development purposes with an H2 database driver. As it is intended for development purposes only, it should never be used in a production environment. + +In this release, the H2 driver has been upgraded from version 1.x to version 2.x. +See link:{upgradingguide_link}[{upgradingguide_name}] for details on how to migrate. diff --git a/upgrading/topics/keycloak/changes-20_0_0.adoc b/upgrading/topics/keycloak/changes-20_0_0.adoc index 2534d517e9..1aeb67ed5d 100644 --- a/upgrading/topics/keycloak/changes-20_0_0.adoc +++ b/upgrading/topics/keycloak/changes-20_0_0.adoc @@ -1,3 +1,30 @@ = RESTEasy Version Update -Updated the RESTEasy version of Keycloak Admin REST Client to the next major version. \ No newline at end of file +Updated the RESTEasy version of Keycloak Admin REST Client to the next major version. + += H2 Version Update + +{project_name} ships for development purposes with an H2 database driver. +As it is intended for development purposes only, it should never be used in a production environment. + +In this release, the H2 driver has been upgraded from version 1.x to version 2.x. +This change might require changes to the H2 JDBC URL or migration of the H2 database files in an existing Keycloak setup. + +== Changes to the H2 JDBC URL + +For Keycloak to run with its JPA legacy store with H2 version 2.x, the JDBC URL requires the attribute `NON_KEYWORDS=VALUE`. + +In a setup where H2 is initialized by Keycloak without extra parameters, Keycloak will append the attribute automatically. +This is the default for development setups. + +If an H2 JDBC URL is provided on the command line or in a configuration file, and it already contains the `NON_KEYWORDS=` attribute in the JDBC URL, this attribute needs to be amended with the `VALUE` keyword. + +If the connection factory for the H2 database is initialized outside Keycloak, that initialization needs to take care of adding the `NON_KEYWORDS` attribute. + +See the H2 documentation http://www.h2database.com/html/commands.html#set_non_keywords[on the `NON_KEYWORDS` attribute] for details. + +== Upgrade of H2 database files + +H2 database base files created with H2 version 1.x should not be used with version 2.x. + +Purge existing H2 database files to start with an empty database, export and import the realms using Keycloak's export and import functionality, or refer to the http://www.h2database.com/html/migration-to-v2.html[migration notes on the H2 database project's website] for details on how to migrate H2 database contents. \ No newline at end of file