UNIX.dog
/
keycloak
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

KEYCLOAK-14968 Update database schema instructions

This commit is contained in:
mposolda 2020-07-31 14:37:41 +02:00 committed by Marek Posolda
parent 32bf50e037
commit 3c4cccd375
1 changed files with 10 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
docs/updating-database-schema.md
View File

@ -21,43 +21,19 @@ We use Liquibase to support updating the database. The change-sets are located i
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
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.
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/utils/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/utils/pom.xml 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/utils/pom.xml exec:java -Pkeycloak-server -Dkeycloak.connectionsJpa.url='jdbc:h2:keycloak' -Dkeycloak.connectionsJpa.databaseSchema='development-validate'
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.
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.