Chapter 15. Importing and exporting the database

Red Hat Single Sign-On includes the ability to export and import its entire database.

You can migrate the whole Red Hat Single Sign-On 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 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:

bin/standalone.sh -Dkeycloak.migration.action=export
-Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=<DIR TO EXPORT TO>

To export into single JSON file:

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:

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 number of users per file. DIFFERENT_FILES is the default value for this property.
  • SKIP - Red Hat Single Sign-On 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.
-Dkeycloak.migration.usersPerFile
This property specifies the number of users per file and database transaction. By default, its value is fifty. Red Hat Single Sign-On uses this property if keycloak.migration.usersExportStrategy is DIFFERENT_FILES.
-Dkeycloak.migration.strategy
Red Hat Single Sign-On 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 Red Hat Single Sign-On 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 Red Hat Single Sign-On 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, Red Hat Single Sign-On ignores the keycloak.import parameter. The keycloak.import mechanism ignores the realms which already exist in Red Hat Single Sign-On. The keycloak.import mechanism is convenient for development purposes, but if more flexibility is needed, use the keycloak.migration.X parameters.

15.1. Admin console export/import

Red Hat Single Sign-On imports most resources from the Admin Console as well as exporting most resources. Red Hat Single Sign-On does not support the export of users.

Note

Red Hat Single Sign-On 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 Red Hat Single Sign-On server may not respond to user requests. Use this feature with caution, especially on a production server.