[[_migrate_db]]

== Migrating the Database

{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 `100000` 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="100000"/>
        </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 => "100000"},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.