Updating export/import chapter
This commit is contained in:
Andy Munro
Marek Posolda
parent
ef1bf867f4
commit
eafa2bb3cf
1 changed files with 70 additions and 61 deletions
|
|
@ -1,46 +1,54 @@
|
|||
|
||||
[id=assembly-exporting-importing_{context}]
|
||||
== Exporting and import the database
|
||||
== Importing and exporting the database
|
||||
[role="_abstract"]
|
||||
{project_name} includes the ability to export and import its entire database.
|
||||
|
||||
{project_name} has the ability to export and import the entire database.
|
||||
This can be especially useful if you want to migrate your whole {project_name} database from one environment to another or migrate to a different database (for example from MySQL to Oracle). Export and import is triggered at server boot time and its parameters are passed in via Java system properties.
|
||||
It is important to note that because import and export happens at server startup, no other actions should be taken on the server or the database while this happens.
|
||||
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.
|
||||
|
||||
You can export/import your database either to:
|
||||
[NOTE]
|
||||
====
|
||||
Because import and export trigger at server startup, take no actions on the server or the database during export/import.
|
||||
====
|
||||
|
||||
* Directory on local filesystem
|
||||
* Single JSON file on your filesystem
|
||||
You can export/import your database to:
|
||||
|
||||
When importing using the directory strategy, note that the files need to follow the naming convention specified below.
|
||||
If you are importing files which were previously exported, the files already follow this convention.
|
||||
* A directory on the filesystem.
|
||||
* A single JSON file on your filesystem.
|
||||
|
||||
* <REALM_NAME>-realm.json, such as "acme-roadrunner-affairs-realm.json" for the realm named "acme-roadrunner-affairs"
|
||||
* <REALM_NAME>-users-<INDEX>.json, such as "acme-roadrunner-affairs-users-0.json" for the first users file of the realm named "acme-roadrunner-affairs"
|
||||
When importing from a directory, the filenames must follow this naming convention:
|
||||
|
||||
If you export to a directory, you can also specify the number of users that will be stored in each JSON file.
|
||||
* <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"
|
||||
|
||||
NOTE: If you have bigger amount of users in your database (500 or more), it's highly recommended to export into directory rather
|
||||
than to single file. Exporting into single file may lead to the very big file. Also the directory provider is using separate transaction for each "page" (file with users),
|
||||
which leads to much better performance.
|
||||
Default count of users per file (and transaction) is 50, which showed us best performance, but you have possibility to override (See below).
|
||||
Exporting to single file is using one transaction per whole export and one per whole import, which results in bad performance with large amount of users.
|
||||
If you export to a directory, you can specify the number of users stored in each JSON file.
|
||||
|
||||
To export into unencrypted directory you can use:
|
||||
[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 you can use:
|
||||
|
||||
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>
|
||||
----
|
||||
And similarly for import just use `-Dkeycloak.migration.action=import` instead of `export` .
|
||||
Here's an example of importing:
|
||||
|
||||
Similarly, for importing,use `-Dkeycloak.migration.action=import` rather than `export`. For example:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
|
@ -49,64 +57,65 @@ bin/standalone.sh -Dkeycloak.migration.action=import
|
|||
-Dkeycloak.migration.strategy=OVERWRITE_EXISTING
|
||||
----
|
||||
|
||||
Other available options are:
|
||||
Other command line options include:
|
||||
|
||||
-Dkeycloak.migration.realmName::
|
||||
This property is used if you want to export just one specified realm instead of all.
|
||||
If not specified, then all realms will be exported.
|
||||
Use this property to export one specifically named realm. If this parameter is not specified, all realms export.
|
||||
|
||||
-Dkeycloak.migration.usersExportStrategy::
|
||||
This property is used to specify where users are exported.
|
||||
Possible values are:
|
||||
* DIFFERENT_FILES - Users will be exported into different files according to the maximum number of users per file. This is default value.
|
||||
* SKIP - Exporting of users will be skipped completely.
|
||||
* REALM_FILE - All users will be exported to same file with the realm settings. (The result will be a file like "foo-realm.json" with both realm data and users.)
|
||||
* SAME_FILE - All users will be exported to same file but different from the realm file. (The result will be a file like "foo-realm.json" with realm data and "foo-users.json" with users.)
|
||||
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 is used to specify the number of users per file (and also per DB transaction). It's 50 by default.
|
||||
It's used only if usersExportStrategy is DIFFERENT_FILES
|
||||
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::
|
||||
This property is used during import.
|
||||
It can be used to specify how to proceed if a realm with same name already exists in the database where you are going to import data.
|
||||
Possible values are:
|
||||
* IGNORE_EXISTING - Ignore importing if a realm of this name already exists.
|
||||
* OVERWRITE_EXISTING - Remove existing realm and import it again with new data from the JSON file.
|
||||
If you want to fully migrate one environment to another and ensure that the new environment will contain the same data
|
||||
as the old one, you can specify this.
|
||||
{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.
|
||||
|
||||
When importing realm files that weren't exported before, the option `keycloak.import` can be used.
|
||||
If more than one realm file needs to be imported, a comma separated list of file names can be specified.
|
||||
This is more appropriate than the cases before, as this will happen only after the master realm has been initialized.
|
||||
Examples:
|
||||
|
||||
* -Dkeycloak.import=/tmp/realm1.json
|
||||
* -Dkeycloak.import=/tmp/realm1.json,/tmp/realm2.json
|
||||
|
||||
NOTE: The mechanism based on `keycloak.import` cannot be used together with the other mechanism based on `keycloak.migration.X` properties.
|
||||
If it is used together, the `keycloak.import` will be ignored. The `keycloak.import` mechanism always ignores the realms, which already
|
||||
exist in {project_name}. Generally the `keycloak.import` mechanism can be convenient for some development purposes, but if more
|
||||
flexibility is needed, we recommend that you stick with the mechanism based on `keycloak.migration.X` properties.
|
||||
[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
|
||||
|
||||
Import of most resources can be performed from the admin console as well as export of most resources.
|
||||
Export of users is not supported.
|
||||
{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: Attributes containing secrets or private information will be masked in export file. Export files obtained via Admin Console
|
||||
are thus not appropriate for backups or data transfer between servers. Only boot-time exports are appropriate for that.
|
||||
[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.
|
||||
====
|
||||
|
||||
The files created during a "startup" export can also be used to import from the admin UI.
|
||||
This way, you can export from one realm and import to another realm. Or, you can export from one server and import to another.
|
||||
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 allows just one realm per file.
|
||||
[NOTE]
|
||||
====
|
||||
The admin console export/import permits one realm per file only.
|
||||
====
|
||||
|
||||
WARNING: The admin console import allows you to "overwrite" resources if you choose.
|
||||
Use this feature with caution, especially on a production system. Export .json files from Admin Console Export operation
|
||||
are generally not appropriate for data import since they contain invalid values for secrets.
|
||||
|
||||
WARNING: The admin console export allows you to export clients, groups, and roles. If there is a great number of any of these
|
||||
assets in your realm, the operation may take some time to complete. During that time server may not be responsive to user requests.
|
||||
Use this feature with caution, especially on a production system.
|
||||
[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.
|
||||
====
|
||||
|
|
|
|||
Loading…
Reference in a new issue