121 lines
6.1 KiB
Text
121 lines
6.1 KiB
Text
|
|
[id=assembly-exporting-importing_{context}]
|
|
== Importing and exporting the database
|
|
[role="_abstract"]
|
|
{project_name} includes the ability to export and import its entire database.
|
|
|
|
You can migrate the whole {project_name} database from one environment to another or migrate to another database. The export/import triggers at server boot time, and its parameters pass through Java properties.
|
|
|
|
[NOTE]
|
|
====
|
|
Because import and export trigger at server startup, take no actions on the server or the database during export/import.
|
|
====
|
|
|
|
You can export/import your database to:
|
|
|
|
* A directory on the filesystem.
|
|
* A single JSON file on your filesystem.
|
|
|
|
When importing from a directory, the filenames must follow this naming convention:
|
|
|
|
* <REALM_NAME>-realm.json. For example, "acme-roadrunner-affairs-realm.json" for the realm named "acme-roadrunner-affairs".
|
|
* <REALM_NAME>-users-<INDEX>.json. For example, "acme-roadrunner-affairs-users-0.json" for the first user's file of the realm named "acme-roadrunner-affairs"
|
|
|
|
If you export to a directory, you can specify the number of users stored in each JSON file.
|
|
|
|
[NOTE]
|
|
====
|
|
Exporting into single files can produce large files, so if your database contains more than 500 users, export to a directory and not a single file. Exporting many users into a directory performs optimally as the directory provider uses a separate transaction for each "page" (a file of users).
|
|
|
|
The default count of users per file and per transaction is fifty, but you can override this number. See <<_keycloak-migration-usersPerFile, keycloak.migration.usersPerFile>> for more information.
|
|
|
|
Exporting to or importing from a single file uses one transaction, which can impair performance if the database contains many users.
|
|
====
|
|
|
|
To export into an unencrypted directory:
|
|
|
|
[source]
|
|
----
|
|
bin/standalone.sh -Dkeycloak.migration.action=export
|
|
-Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=<DIR TO EXPORT TO>
|
|
----
|
|
|
|
To export into single JSON file:
|
|
|
|
[source]
|
|
----
|
|
bin/standalone.sh -Dkeycloak.migration.action=export
|
|
-Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=<FILE TO EXPORT TO>
|
|
----
|
|
|
|
Similarly, for importing,use `-Dkeycloak.migration.action=import` rather than `export`. For example:
|
|
|
|
[source]
|
|
----
|
|
bin/standalone.sh -Dkeycloak.migration.action=import
|
|
-Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=<FILE TO IMPORT>
|
|
-Dkeycloak.migration.strategy=OVERWRITE_EXISTING
|
|
----
|
|
|
|
Other command line options include:
|
|
|
|
-Dkeycloak.migration.realmName::
|
|
Use this property to export one specifically named realm. If this parameter is not specified, all realms export.
|
|
|
|
-Dkeycloak.migration.usersExportStrategy::
|
|
This property specifies where users export to. Possible values include:
|
|
|
|
* DIFFERENT_FILES - Users export into different files subject to the maximum <<_keycloak-migration-usersPerFile, number of users per file>>. DIFFERENT_FILES is the default value for this property.
|
|
* SKIP - {project_name} skips exporting users.
|
|
* REALM_FILE - Users export to the same file with the realm settings. The file is similar to "foo-realm.json" with realm data and users.
|
|
* SAME_FILE - Users export to the same file but different from the realm file. The result is similar to "foo-realm.json" with realm data and "foo-users.json" with users.
|
|
|
|
[[_keycloak-migration-usersPerFile]]
|
|
-Dkeycloak.migration.usersPerFile::
|
|
This property specifies the number of users per file and database transaction. By default, its value is fifty. {project_name} uses this property if keycloak.migration.usersExportStrategy is DIFFERENT_FILES.
|
|
|
|
-Dkeycloak.migration.strategy::
|
|
{project_name} uses this property when importing. It specifies how to proceed when a realm with the same name already exists in the database.
|
|
|
|
Possible values are:
|
|
|
|
* IGNORE_EXISTING - Do not import a realm if a realm with the same name already exists.
|
|
* OVERWRITE_EXISTING - Remove the existing realm and import the realm again with new data from the JSON file. Use this value to migrate from one environment to another fully.
|
|
|
|
If you are importing files that are not from a {project_name} export, use the `keycloak.import` option. If you are importing more than one realm file, specify a comma-separated list of filenames. A list of filenames is more suitable than the previous cases because this happens after {project_name} initializes the master realm.
|
|
|
|
Examples:
|
|
|
|
* -Dkeycloak.import=/tmp/realm1.json
|
|
* -Dkeycloak.import=/tmp/realm1.json,/tmp/realm2.json
|
|
|
|
[NOTE]
|
|
====
|
|
You cannot use the `keycloak.import` parameter with `keycloak.migration.X` parameters. If you use these parameters together, {project_name} ignores the `keycloak.import` parameter. The `keycloak.import` mechanism ignores the realms which already exist in {project_name}. The `keycloak.import` mechanism is convenient for development purposes, but if more flexibility is needed, use the `keycloak.migration.X` parameters.
|
|
====
|
|
|
|
=== Admin console export/import
|
|
|
|
{project_name} imports most resources from the Admin Console as well as exporting most resources. {project_name} does not support the export of users.
|
|
|
|
[NOTE]
|
|
====
|
|
{project_name} masks attributes containing secrets or private information in the export file. Export files from the Admin Console are not suitable for backups or data transfer between servers. Only boot-time exports are suitable for backups or data transfer between servers.
|
|
====
|
|
|
|
You can use the files created during an export to import from the Admin Console. You can export from one realm and import to another realm, or you can export from one server and import to another.
|
|
|
|
[NOTE]
|
|
====
|
|
The admin console export/import permits one realm per file only.
|
|
====
|
|
|
|
[WARNING]
|
|
====
|
|
The Admin Console import can overwrite resources. Use this feature with caution, especially on a production server. JSON files from the Admin Console Export operation are not appropriate for data import because they contain invalid values for secrets.
|
|
====
|
|
|
|
[WARNING]
|
|
====
|
|
You can use the Admin Console to export clients, groups, and roles. If the database in your realm contains many clients, groups, and roles, the export may take a long time to conclude, and the {project_name} server may not respond to user requests. Use this feature with caution, especially on a production server.
|
|
====
|