Skip to content

Improve documentation about manual database migration #23247

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mhajas merged 1 commit into from
Sep 15, 2023
Merged

Improve documentation about manual database migration #23247

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 17 additions & 16 deletions docs/documentation/upgrading/topics/migrate_db.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,8 @@ database is automatically migrated when you start the new installation for the f

=== Automatic relational database migration

To enable automatic upgrading of the database schema, set the migration-strategy property value to "update" for the
default connections-jpa provider:

[source,bash]
----
kc.[sh|bat] start --spi-connections-jpa-legacy-migration-strategy=update
----

When you start the server with this setting your database is automatically migrated if the database schema has changed
in the new version.
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.

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.
Expand All @@ -34,16 +26,25 @@ kc.[sh|bat] start --spi-connections-liquibase-default-index-creation-threshold=3

=== Manual relational database migration

To enable manual upgrading of the database schema, set the migration-strategy property value to "manual" for the default
connections-jpa provider:
To enable manual upgrading of the database schema, set the `migration-strategy` property value to "manual" for the
default `connections-jpa` provider:

[source,bash]
----
kc.[sh|bat] start --spi-connections-jpa-legacy-migration-strategy=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.
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.