JBoss.orgCommunity Documentation
Export/import is useful especially if you want to migrate your whole Keycloak database from one environment to another or migrate to different database (For example from MySQL to Oracle). You can trigger export/import at startup of Keycloak server and it's configurable with System properties right now. The fact it's done at server startup means that no-one can access Keycloak UI or REST endpoints and edit Keycloak database on the fly when export or import is in progress. Otherwise it could lead to inconsistent results.
You can export/import your database either to:
Encrypted ZIP is recommended as export contains many sensitive informations like passwords of your users (even if they are hashed), but also their email addresses, and especially private keys of the realms. Directory and Single JSON file are useful especially for testing as data in the files are not protected. On the other hand, it's useful if you want to look at all your data in JSON files directly.
If you import to ZIP or Directory, you can specify also the number of users to be stored in each JSON file. So if you have very large amount of users in your database, you likely don't want to import them into single file as the file might be very big. Processing of each file is done in separate transaction as exporting/importing all users at once could also lead to memory issues.
So to export the content of your Keycloak database into encrypted ZIP, you can execute Keycloak server with the System properties like:
bin/standalone.sh -Dkeycloak.migration.action=export -Dkeycloak.migration.provider=zip -Dkeycloak.migration.zipFile=<FILE TO EXPORT TO> -Dkeycloak.migration.zipPassword=<PASSWORD TO DECRYPT EXPORT>
Then you can move or copy the encrypted ZIP file into second environment and you can trigger import from it into Keycloak server with the same command but use
-Dkeycloak.migration.action=import
instead of export
.
To export into unencrypted directory you can use:
bin/standalone.sh -Dkeycloak.migration.action=export -Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=<DIR TO EXPORT TO>
And similarly for import just use -Dkeycloak.migration.action=import
instead of export
.
To export into single JSON file you can use:
bin/standalone.sh -Dkeycloak.migration.action=export -Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=<FILE TO EXPORT TO>
Here's an example of importing:
bin/standalone.sh -Dkeycloak.migration.action=import -Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=<FILE TO IMPORT> -Dkeycloak.migration.strategy=OVERWRITE_EXISTING
Other available options are:
can be used if you want to export just one specified realm instead of all. If not specified, then all realms will be exported.
can be used to specify for ZIP or Directory providers to specify where to import users. Possible values are:
can be used to specify number of users per file (and also per DB transaction). It's 5000 by default. It's used only if usersExportStrategy is DIFFERENT_FILES
is used during import. It can be used to specify how to proceed if realm with same name already exists in the database where you are going to import data. Possible values are: