keycloak-scim/docs/updating-database-schema.md

Updating Database Schema
========================

Keycloak supports automatically migrating the database to a new version. This is done by applying one or more change-sets
to the existing database. This means if you need to do any changes to database schemas you need to create 
a change-set that can transform the schema as well as any existing data.

This includes changes to:
 
* Realm entities
* User entities
* User session entities
* Event entities

 
Creating a change-set
-------------------------

We use Liquibase to support updating the database. The change-sets are located in 
[`model/jpa/src/main/resources/META-INF`](../model/jpa/src/main/resources/META-INF).
There's a separate file for each release that requires database changes.

To manually create a change-set add a new file in the above location with the name `jpa-changelog-<version>.xml`. This file 
should contain a single `change-set` with `id` equal to the next version to be released and `author` set to the value `keycloak` 
. Then look at Liquibase documentation on how to write this file. Other option can be to look at existing changesets for the inspiration
and create your changeset based on them. Add a reference to this file in
[`jpa-changelog-master.xml`](../model/jpa/src/main/resources/META-INF/jpa-changelog-master.xml).
The file should have a single change-set and the id of the change-set should be the next version to be released. 

Testing database migration
--------------------------

The first step may be to re-build Keycloak and check if server is started fully. This means that server can be started against
empty DB with your changes. You can either use testing server based on embedded undertow or build fully distribution. See 
[`building.md`](building.md) and [`tests.md`](tests.md) for more details. Also see [`tests-db.md`](tests-db.md) for testing on the
more production non-H2 database.

It is good idea to run DB migration afterwards. See [`testsuite/integration-arquillian/HOW-TO-RUN.md`](../testsuite/integration-arquillian/HOW-TO-RUN.md#db-migration-test)
for more details.
KEYCLOAK-736 Database migration support" 2014-10-07 08:23:15 +00:00			`Updating Database Schema`
			`========================`

			`Keycloak supports automatically migrating the database to a new version. This is done by applying one or more change-sets`
KEYCLOAK-4384 Remove Mongo support 2017-02-06 19:22:43 +00:00			`to the existing database. This means if you need to do any changes to database schemas you need to create`
KEYCLOAK-736 Database migration support" 2014-10-07 08:23:15 +00:00			`a change-set that can transform the schema as well as any existing data.`

			`This includes changes to:`

			`* Realm entities`
			`* User entities`
			`* User session entities`
			`* Event entities`


KEYCLOAK-4384 Remove Mongo support 2017-02-06 19:22:43 +00:00			`Creating a change-set`
KEYCLOAK-736 Database migration support" 2014-10-07 08:23:15 +00:00			`-------------------------`

			`We use Liquibase to support updating the database. The change-sets are located in`
KEYCLOAK-3697: Evaluate preconditions when generating SQL script Plus minor related change - replace deprecated call with equivalent supported, add javadoc Further info: * http://forum.liquibase.org/topic/unexpected-behaviour-of-preconditions-with-updatesql * http://stackoverflow.com/questions/17671923/liquibase-migrate-sql-does-not-check-precondtions 2016-10-13 08:55:34 +00:00			[`model/jpa/src/main/resources/META-INF`](../model/jpa/src/main/resources/META-INF).
			`There's a separate file for each release that requires database changes.`
KEYCLOAK-736 Database migration support" 2014-10-07 08:23:15 +00:00
			To manually create a change-set add a new file in the above location with the name `jpa-changelog-<version>.xml`. This file
KEYCLOAK-14968 Update database schema instructions 2020-07-31 12:37:41 +00:00			should contain a single `change-set` with `id` equal to the next version to be released and `author` set to the value `keycloak`
			`. Then look at Liquibase documentation on how to write this file. Other option can be to look at existing changesets for the inspiration`
			`and create your changeset based on them. Add a reference to this file in`
KEYCLOAK-3697: Evaluate preconditions when generating SQL script Plus minor related change - replace deprecated call with equivalent supported, add javadoc Further info: * http://forum.liquibase.org/topic/unexpected-behaviour-of-preconditions-with-updatesql * http://stackoverflow.com/questions/17671923/liquibase-migrate-sql-does-not-check-precondtions 2016-10-13 08:55:34 +00:00			[`jpa-changelog-master.xml`](../model/jpa/src/main/resources/META-INF/jpa-changelog-master.xml).
KEYCLOAK-736 Database migration support" 2014-10-07 08:23:15 +00:00			`The file should have a single change-set and the id of the change-set should be the next version to be released.`

			`Testing database migration`
			`--------------------------`

KEYCLOAK-14968 Update database schema instructions 2020-07-31 12:37:41 +00:00			`The first step may be to re-build Keycloak and check if server is started fully. This means that server can be started against`
			`empty DB with your changes. You can either use testing server based on embedded undertow or build fully distribution. See`
			[`building.md`](building.md) and [`tests.md`](tests.md) for more details. Also see [`tests-db.md`](tests-db.md) for testing on the
			`more production non-H2 database.`

			It is good idea to run DB migration afterwards. See [`testsuite/integration-arquillian/HOW-TO-RUN.md`](../testsuite/integration-arquillian/HOW-TO-RUN.md#db-migration-test)
			`for more details.`