6578ce73a1
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
77 lines
4.1 KiB
Markdown
77 lines
4.1 KiB
Markdown
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 for JPA or Mongo 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 JPA 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 your email
|
|
address. Then look at Liquibase documentation on how to write this file. 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.
|
|
|
|
You can also have Liquibase and Hibernate create one for you. To do this follow these steps:
|
|
|
|
1. Delete existing databases
|
|
`rm keycloak*h2.db`
|
|
2. Create a database of the old format:
|
|
`mvn -f connections/jpa-liquibase/pom.xml liquibase:update -Durl=jdbc:h2:keycloak`
|
|
3. Make a copy of the database:
|
|
`cp keycloak.h2.db keycloak-old.h2.db`
|
|
3. Run KeycloakServer to make Hibernate update the schema:
|
|
`mvn -f testsuite/integration/pom.xml exec:java -Pkeycloak-server -Dkeycloak.connectionsJpa.url='jdbc:h2:keycloak' -Dkeycloak.connectionsJpa.databaseSchema='development-update'`
|
|
4. Wait until server is completely started, then stop it
|
|
5. View the difference:
|
|
`mvn -f connections/jpa-liquibase/pom.xml liquibase:diff -Durl=jdbc:h2:keycloak-old -DreferenceUrl=jdbc:h2:keycloak`
|
|
6. Create a change-set file:
|
|
`mvn -f connections/jpa-liquibase/pom.xml liquibase:diff -Durl=jdbc:h2:keycloak-old -DreferenceUrl=jdbc:h2:keycloak -Dliquibase.diffChangeLogFile=changelog.xml`
|
|
|
|
This will generate the file `changelog.xml`. Once it's generated edit the file and combine all `change-sets` into
|
|
a single `change-set` and change the `id` to the next version to be released and `author` to your email address. Then
|
|
follow the steps above to copy it to the correct location and update `jpa-changelog-master.xml`. You have to manually
|
|
add entries to the `change-set` to update existing data if required.
|
|
|
|
When you have update the change-set Hibernate can validate the schema for you. First run:
|
|
|
|
rm -rf keycloak*h2.db
|
|
mvn -f testsuite/integration exec:java -Pkeycloak-server -Dkeycloak.connectionsJpa.url='jdbc:h2:keycloak' -Dkeycloak.connectionsJpa.databaseSchema='update'
|
|
|
|
Once the server has started fully, stop it and run:
|
|
|
|
mvn -f testsuite/integration exec:java -Pkeycloak-server -Dkeycloak.connectionsJpa.url='jdbc:h2:keycloak' -Dkeycloak.connectionsJpa.databaseSchema='development-validate'
|
|
|
|
|
|
Creating a Mongo change-set
|
|
---------------------------
|
|
|
|
As Mongo is schema-less it's significantly easier to create a change-set. You only need to create/delete collections as
|
|
needed, as well as update any indexes. You will also need to update existing data if required.
|
|
|
|
Mongo change-sets are written in Java and are located in the `connections/mongo` module, to add a new change-set create
|
|
a new class that implements `org.keycloak.connections.mongo.updater.updates.Update` the name of the class should be
|
|
`Update<version>` with `.` replaced with `_`.
|
|
|
|
You also need to add a reference to this file in `org.keycloak.connections.mongo.updater.DefaultMongoUpdaterProvider`.
|
|
It should be added last to the `DefaultMongoUpdaterProvider#updates` array.
|
|
|
|
|
|
Testing database migration
|
|
--------------------------
|
|
|
|
Get the database from an old version of Keycloak that includes the demo applications. Start the server with this and test it.
|