91 lines
3.1 KiB
Text
91 lines
3.1 KiB
Text
[[_migrate_db]]
|
|
|
|
== Database migration
|
|
|
|
{project_name} can automatically migrate the database schema, or you can choose to do it manually. By default the
|
|
database is automatically migrated when you start the new installation for the first time.
|
|
|
|
=== Automatic relational database migration
|
|
|
|
To enable automatic upgrading of the database schema, set the migrationStrategy property value to "update" for the
|
|
default connectionsJpa provider:
|
|
|
|
[source,xml]
|
|
----
|
|
<spi name="connectionsJpa">
|
|
<provider name="default" enabled="true">
|
|
<properties>
|
|
...
|
|
<property name="migrationStrategy" value="update"/>
|
|
</properties>
|
|
</provider>
|
|
</spi>
|
|
----
|
|
|
|
Or run this CLI command:
|
|
|
|
[source,bash]
|
|
----
|
|
/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)
|
|
----
|
|
|
|
When you start the server with this setting your database is automatically migrated if the database schema has changed
|
|
in the new version.
|
|
|
|
Creating an index on huge tables with millions of records can easily take a huge amount of time
|
|
and potentially cause major service disruption on upgrades.
|
|
For those cases, we added a threshold (the number of records) for automated index creation.
|
|
By default, this threshold is `300000` records.
|
|
When the number of records is higher than the threshold, the index is not created automatically,
|
|
and there will be a warning message in server logs including SQL commands which can be applied later manually.
|
|
|
|
To change the threshold, set the `indexCreationThreshold` property, value for the default `connectionsLiquibase` provider:
|
|
|
|
[source,xml]
|
|
----
|
|
<spi name="connectionsLiquibase">
|
|
<provider name="default" enabled="true">
|
|
<properties>
|
|
<property name="indexCreationThreshold" value="300000"/>
|
|
</properties>
|
|
</provider>
|
|
</spi>
|
|
----
|
|
|
|
Or run this CLI command:
|
|
|
|
[source,bash]
|
|
----
|
|
/subsystem=keycloak-server/spi=connectionsLiquibase/:add(default-provider=default)
|
|
/subsystem=keycloak-server/spi=connectionsLiquibase/provider=default/:add(properties={indexCreationThreshold => "300000"},enabled=true)
|
|
----
|
|
|
|
=== Manual relational database migration
|
|
|
|
To enable manual upgrading of the database schema, set the migrationStrategy property value to "manual" for the default
|
|
connectionsJpa provider:
|
|
|
|
[source,xml]
|
|
----
|
|
<spi name="connectionsJpa">
|
|
<provider name="default" enabled="true">
|
|
<properties>
|
|
...
|
|
<property name="migrationStrategy" value="manual"/>
|
|
</properties>
|
|
</provider>
|
|
</spi>
|
|
----
|
|
|
|
Or run this CLI command:
|
|
|
|
[source,bash]
|
|
----
|
|
/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=manual)
|
|
----
|
|
|
|
When you start the server with this configuration it checks if the database needs to be migrated. The required changes
|
|
are written to an SQL file that you can review and manually run against the database. For further details on how to
|
|
apply this file to the database, see the documentation for the relational database you're using. After the changes have
|
|
been written to the file, the server exits.
|
|
|