KEYCLOAK-3456 Update instructions in migration documentation around db migration
This commit is contained in:
Stian Thorgersen
parent
8d2a42e688
commit
a022a407e2
1 changed files with 60 additions and 22 deletions
|
|
@ -1,41 +1,70 @@
|
|||
== Migration from older versions
|
||||
|
||||
To upgrade to a new version of Keycloak first download and install the new version of Keycloak.
|
||||
You then have to migrate the database, keycloak-server.json, providers, themes and applications from the old version.
|
||||
To upgrade to a new version of Keycloak first download and install the new version of Keycloak. Once the new version
|
||||
is installed migrate the database, keycloak-server.json, providers, themes and applications to the new applications.
|
||||
|
||||
This chapter contains some general migration details which are applicable to all versions. There are instructions for
|
||||
migration that is only applicable to a specific release. If you are upgrading from a very old version you need to go
|
||||
through all intermediate version specific migration.
|
||||
|
||||
It's highly recommended that you backup your database prior to upgrading Keycloak.
|
||||
|
||||
Migration from a candidate release (CR) to a Final release is not supported. We do however recommend that you test
|
||||
migration for a CR so we can resolve any potential issues before the Final is released.
|
||||
|
||||
=== Migrate database
|
||||
|
||||
Keycloak provides automatic migration of the database.
|
||||
It's highly recommended that you backup your database prior to upgrading Keycloak. Migrating from a release candidate to
|
||||
a final release is not supported. For reason for release candidates we recommend that you create a copy of your production
|
||||
database to test release candidates.
|
||||
Keycloak can automatically migration the database schema, or you can choose to do it manually.
|
||||
|
||||
To enable automatic upgrading of the database if you're using a relational database make sure `databaseSchema` is set to `update` for `connectionsJpa`:
|
||||
==== Relational database
|
||||
|
||||
To enable automatic upgrading of the database schema set the `migrationStrategy` property to `update` for
|
||||
the default `connectionsJpa` provider:
|
||||
|
||||
[source]
|
||||
----
|
||||
"connectionsJpa": {
|
||||
"default": {
|
||||
...
|
||||
"databaseSchema": "update"
|
||||
}
|
||||
}
|
||||
<spi name="connectionsJpa">
|
||||
<provider name="default" enabled="true">
|
||||
<properties>
|
||||
...
|
||||
<property name="migrationStrategy" value="update"/>
|
||||
</properties>
|
||||
</provider>
|
||||
</spi>
|
||||
----
|
||||
|
||||
For MongoDB do the same, but for `connectionsMongo`:
|
||||
When you start the server with this setting your database will automatically be migrated if the database schema has
|
||||
changed in the new version.
|
||||
|
||||
To manually migrate the database set the `migrationStrategy` to `manual`. When you start the server with this
|
||||
configuration it will check if the database needs migration. If changes are needed the required changes are written
|
||||
to an SQL file that you can review and manually run against the database.
|
||||
|
||||
There's also the option to disable migration by setting the `migrationStrategy` to `validate`. With this configuration
|
||||
the database will be checked at startup and if it is not migrated the server will exit.
|
||||
|
||||
====
|
||||
|
||||
Mongo doesn't have a schema, but there may still be things like collections and indexes that are added to new releases.
|
||||
To enable automatic creation of these set the `migrationStrategy` property to `update` for the default `connectionsMongo`
|
||||
provider:
|
||||
|
||||
[source]
|
||||
----
|
||||
<spi name="connectionsMongo">
|
||||
<provider name="default" enabled="true">
|
||||
<properties>
|
||||
...
|
||||
<property name="migrationStrategy" value="update"/>
|
||||
</properties>
|
||||
</provider>
|
||||
</spi>
|
||||
----
|
||||
|
||||
"connectionsMongo": {
|
||||
"default": {
|
||||
...
|
||||
"databaseSchema": "update"
|
||||
}
|
||||
}
|
||||
----
|
||||
The Mongo provider does not have the option to manually apply the required changes.
|
||||
|
||||
When you start the server with this setting your database will automatically be migrated if the database schema has changed in the new version.
|
||||
There's also the option to disable migration by setting the `migrationStrategy` to `validate`. With this configuration
|
||||
the database will be checked at startup and if it is not migrated the server will exit.
|
||||
|
||||
=== Migrate keycloak-server.json
|
||||
|
||||
|
|
@ -62,6 +91,15 @@ The version specific section below will mention if any changes are required to a
|
|||
|
||||
=== Version specific migration
|
||||
|
||||
==== Migrating to 2.2.0
|
||||
|
||||
====== `databaseSchema` property deprecated
|
||||
|
||||
The `databaseSchema` property for both JPA and Mongo is now deprecated and has been replaced by `initializeEmpty`
|
||||
and `migrationStrategy`. `initializeEmpty` can bet set to `true` or `false` and controls if an empty database should
|
||||
be initialized. `migrationStrategy` can be set to `update`, `validate` and `manual`. `manual` is only supported for
|
||||
relational databases and will write an SQL file with the required changes to the database schema.
|
||||
|
||||
==== Migrating to 2.0.0
|
||||
|
||||
====== Upgrading from 1.0.0.Final no longer supported
|
||||
|
|
|
|||
Loading…
Reference in a new issue