2017-09-01 03:25:47 +00:00
|
|
|
[[_migrate_db]]
|
|
|
|
|
|
2021-06-18 01:03:51 +00:00
|
|
|
== Database migration
|
2017-09-01 03:25:47 +00:00
|
|
|
|
|
|
|
|
{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.
|
|
|
|
|
|
2021-06-18 01:03:51 +00:00
|
|
|
=== Automatic relational database migration
|
2017-09-01 03:25:47 +00:00
|
|
|
|
2023-09-15 08:41:33 +00:00
|
|
|
To perform an automatic migration, start the server connected to the desired database.
|
|
|
|
|
If the database schema has changed for the new version of the server, it will be migrated.
|
2017-09-01 03:25:47 +00:00
|
|
|
|
2020-12-11 07:51:49 +00:00
|
|
|
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.
|
2021-05-27 11:28:29 +00:00
|
|
|
By default, this threshold is `300000` records.
|
2020-12-11 07:51:49 +00:00
|
|
|
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.
|
|
|
|
|
|
2022-08-19 11:15:51 +00:00
|
|
|
To change the threshold, set the `index-creation-threshold` property, value for the default `connections-liquibase` provider:
|
2020-12-11 07:51:49 +00:00
|
|
|
|
|
|
|
|
[source,bash]
|
|
|
|
|
----
|
2022-08-19 11:15:51 +00:00
|
|
|
kc.[sh|bat] start --spi-connections-liquibase-default-index-creation-threshold=300000
|
2020-12-11 07:51:49 +00:00
|
|
|
----
|
|
|
|
|
|
2021-06-18 01:03:51 +00:00
|
|
|
=== Manual relational database migration
|
2017-09-01 03:25:47 +00:00
|
|
|
|
2023-09-15 08:41:33 +00:00
|
|
|
To enable manual upgrading of the database schema, set the `migration-strategy` property value to "manual" for the
|
|
|
|
|
default `connections-jpa` provider:
|
2017-09-01 03:25:47 +00:00
|
|
|
|
|
|
|
|
[source,bash]
|
|
|
|
|
----
|
2022-08-19 11:15:51 +00:00
|
|
|
kc.[sh|bat] start --spi-connections-jpa-legacy-migration-strategy=manual
|
2017-09-01 03:25:47 +00:00
|
|
|
----
|
|
|
|
|
|
2023-09-15 08:41:33 +00:00
|
|
|
When you start the server with this configuration it checks if the database needs to be migrated.
|
|
|
|
|
The required changes are written to the `bin/keycloak-database-update.sql` SQL file that you can review and manually run against the database.
|
|
|
|
|
|
|
|
|
|
To change the path and name of the exported SQL file, set the `migration-export` property for the
|
|
|
|
|
default `connections-jpa` provider:
|
|
|
|
|
|
|
|
|
|
[source,bash]
|
|
|
|
|
----
|
|
|
|
|
kc.[sh|bat] start --spi-connections-jpa-legacy-migration-export=<path>/<file.sql>
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
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.
|
2021-06-18 01:03:51 +00:00
|
|
|
|
