Updating performance information on export/import

Closes: #20703

1.txt

@@ -0,0 +1,206 @@
+Export data from realms to a file or directory.
+
+Usage:
+
+kc.sh export [OPTIONS]
+
+Export data from realms to a file or directory.
+
+Options:
+
+-h, --help           This help message.
+--help-all           This same help message but with additional options.
+--optimized          Use this option to achieve an optimal startup time if you have previously
+                       built a server image using the 'build' command.
+
+Storage (Experimental):
+
+--storage <type>     Experimental: Sets the default storage mechanism for all areas. Possible
+                       values are: jpa, chm, hotrod, file.
+--storage-area-auth-session <type>
+                     Experimental: Sets a storage mechanism for authentication sessions. Possible
+                       values are: jpa, chm, hotrod, file.
+--storage-area-authorization <type>
+                     Experimental: Sets a storage mechanism for authorizations. Possible values
+                       are: jpa, chm, hotrod, file.
+--storage-area-client <type>
+                     Experimental: Sets a storage mechanism for clients. Possible values are: jpa,
+                       chm, hotrod, file.
+--storage-area-client-scope <type>
+                     Experimental: Sets a storage mechanism for client scopes. Possible values are:
+                       jpa, chm, hotrod, file.
+--storage-area-event-admin <type>
+                     Experimental: Sets a storage mechanism for admin events. Possible values are:
+                       jpa, chm, hotrod, file.
+--storage-area-event-auth <type>
+                     Experimental: Sets a storage mechanism for authentication and authorization
+                       events. Possible values are: jpa, chm, hotrod, file.
+--storage-area-group <type>
+                     Experimental: Sets a storage mechanism for groups. Possible values are: jpa,
+                       chm, hotrod, file.
+--storage-area-login-failure <type>
+                     Experimental: Sets a storage mechanism for login failures. Possible values
+                       are: jpa, chm, hotrod, file.
+--storage-area-realm <type>
+                     Experimental: Sets a storage mechanism for realms. Possible values are: jpa,
+                       chm, hotrod, file.
+--storage-area-role <type>
+                     Experimental: Sets a storage mechanism for roles. Possible values are: jpa,
+                       chm, hotrod, file.
+--storage-area-single-use-object <type>
+                     Experimental: Sets a storage mechanism for single use objects. Possible values
+                       are: jpa, chm, hotrod.
+--storage-area-user <type>
+                     Experimental: Sets a storage mechanism for users. Possible values are: jpa,
+                       chm, hotrod, file.
+--storage-area-user-session <type>
+                     Experimental: Sets a storage mechanism for user and client sessions. Possible
+                       values are: jpa, chm, hotrod, file.
+--storage-deployment-state-version-seed <type>
+                     Experimental: Secret that serves as a seed to mask the version number of
+                       Keycloak in URLs. Need to be identical across all servers in the cluster.
+                       Will default to a random number generated when starting the server which is
+                       secure but will lead to problems when a loadbalancer without sticky sessions
+                       is used or nodes are restarted.
+--storage-file-dir <dir>
+                     Experimental: Root directory for file map store.
+--storage-hotrod-host <host>
+                     Experimental: Sets the host of the Infinispan server.
+--storage-hotrod***
+                     Experimental: Sets the password of the Infinispan user.
+--storage-hotrod-port <port>
+                     Experimental: Sets the port of the Infinispan server.
+--storage-hotrod-username <username>
+                     Experimental: Sets the username of the Infinispan user.
+--storage-jpa-db <type>
+                     Experimental: The database vendor for jpa map storage. Possible values are:
+                       postgres, cockroach. Default: postgres.
+
+Database:
+
+--db <vendor>        The database vendor. Possible values are: dev-file, dev-mem, mariadb, mssql,
+                       mysql, oracle, postgres. Default: dev-file.
+--db-driver <driver> The fully qualified class name of the JDBC driver. If not set, a default
+                       driver is set accordingly to the chosen database.
+--db***
+                     The password of the database user.
+--db-pool-initial-size <size>
+                     The initial size of the connection pool.
+--db-pool-max-size <size>
+                     The maximum size of the connection pool. Default: 100.
+--db-pool-min-size <size>
+                     The minimal size of the connection pool.
+--db-schema <schema> The database schema to be used.
+--db-url <jdbc-url>  The full database JDBC URL. If not provided, a default URL is set based on the
+                       selected database vendor. For instance, if using 'postgres', the default
+                       JDBC URL would be 'jdbc:postgresql://localhost/keycloak'.
+--db-url-database <dbname>
+                     Sets the database name of the default JDBC URL of the chosen vendor. If the
+                       `db-url` option is set, this option is ignored.
+--db-url-host <hostname>
+                     Sets the hostname of the default JDBC URL of the chosen vendor. If the
+                       `db-url` option is set, this option is ignored.
+--db-url-port <port> Sets the port of the default JDBC URL of the chosen vendor. If the `db-url`
+                       option is set, this option is ignored.
+--db-url-properties <properties>
+                     Sets the properties of the default JDBC URL of the chosen vendor. Make sure to
+                       set the properties accordingly to the format expected by the database
+                       vendor, as well as appending the right character at the beginning of this
+                       property value. If the `db-url` option is set, this option is ignored.
+--db-username <username>
+                     The username of the database user.
+
+Transaction:
+
+--transaction-xa-enabled <true|false>
+                     If set to false, Keycloak uses a non-XA datasource in case the database does
+                       not support XA transactions. Default: true.
+
+Feature:
+
+--features <feature> Enables a set of one or more features. Possible values are: account-api,
+                       account2, account3, admin-api, admin-fine-grained-authz, admin2,
+                       authorization, ciba, client-policies, client-secret-rotation,
+                       declarative-user-profile, docker, dynamic-scopes, fips, impersonation,
+                       js-adapter, kerberos, map-storage, par, preview, recovery-codes, scripts,
+                       step-up-authentication, token-exchange, update-email, web-authn.
+--features-disabled <feature>
+                     Disables a set of one or more features. Possible values are: account-api,
+                       account2, account3, admin-api, admin-fine-grained-authz, admin2,
+                       authorization, ciba, client-policies, client-secret-rotation,
+                       declarative-user-profile, docker, dynamic-scopes, fips, impersonation,
+                       js-adapter, kerberos, map-storage, par, preview, recovery-codes, scripts,
+                       step-up-authentication, token-exchange, update-email, web-authn.
+
+Config:
+
+--config-keystore <config-keystore>
+                     Specifies a path to the KeyStore Configuration Source.
+--config-keystore***
+                     Specifies a password to the KeyStore Configuration Source.
+--config-keystore-type <config-keystore-type>
+                     Specifies a type of the KeyStore Configuration Source. Default: PKCS12.
+
+Logging:
+
+--log <handler>      Enable one or more log handlers in a comma-separated list. Possible values
+                       are: console, file, gelf. Default: console.
+--log-console-color <true|false>
+                     Enable or disable colors when logging to console. Default: false.
+--log-console-format <format>
+                     The format of unstructured console log entries. If the format has spaces in
+                       it, escape the value using "<format>". Default: %d{yyyy-MM-dd HH:mm:ss,SSS} %
+                       -5p [%c] (%t) %s%e%n.
+--log-console-output <output>
+                     Set the log output to JSON or default (plain) unstructured logging. Possible
+                       values are: default, json. Default: default.
+--log-file <file>    Set the log file path and filename. Default: data/log/keycloak.log.
+--log-file-format <format>
+                     Set a format specific to file log entries. Default: %d{yyyy-MM-dd HH:mm:ss,
+                       SSS} %-5p [%c] (%t) %s%e%n.
+--log-file-output <output>
+                     Set the log output to JSON or default (plain) unstructured logging. Possible
+                       values are: default, json. Default: default.
+--log-gelf-facility <name>
+                     The facility (name of the process) that sends the message. Default: keycloak.
+--log-gelf-host <hostname>
+                     Hostname of the Logstash or Graylog Host. By default UDP is used, prefix the
+                       host with 'tcp:' to switch to TCP. Example: 'tcp:localhost' Default:
+                       localhost.
+--log-gelf-include-location <true|false>
+                     Include source code location. Default: true.
+--log-gelf-include-message-parameters <true|false>
+                     Include message parameters from the log event. Default: true.
+--log-gelf-include-stack-trace <true|false>
+                     If set to true, occuring stack traces are included in the 'StackTrace' field
+                       in the GELF output. Default: true.
+--log-gelf-level <level>
+                     The log level specifying which message levels will be logged by the GELF
+                       logger. Message levels lower than this value will be discarded. Default:
+                       INFO.
+--log-gelf-max-message-size <size>
+                     Maximum message size (in bytes). If the message size is exceeded, GELF will
+                       submit the message in multiple chunks. Default: 8192.
+--log-gelf-port <port>
+                     The port the Logstash or Graylog Host is called on. Default: 12201.
+--log-gelf-timestamp-format <pattern>
+                     Set the format for the GELF timestamp field. Uses Java SimpleDateFormat
+                       pattern. Default: yyyy-MM-dd HH:mm:ss,SSS.
+--log-level <category:level>
+                     The log level of the root category or a comma-separated list of individual
+                       categories and their levels. For the root category, you don't need to
+                       specify a category. Default: info.
+
+Export:
+
+--dir <dir>          Set the path to a directory where files will be created with the exported data.
+--file <file>        Set the path to a file that will be created with the exported data. To export
+                       more than 500 users, export to a directory with different files instead.
+--realm <realm>      Set the name of the realm to export. If not set, all realms are going to be
+                       exported.
+--users <strategy>   Set how users should be exported. Possible values are: skip, realm_file,
+                       same_file, different_files. Default: different_files.
+--users-per-file <number>
+                     Set the number of users per file. It is used only if 'users' is set to
+                       'different_files'. Increasing this number leads to exponentially increased
+                       export times. Default: 50.

2.txt

@@ -0,0 +1,206 @@
+Export data from realms to a file or directory.
+
+Usage:
+
+kc.sh export [OPTIONS]
+
+Export data from realms to a file or directory.
+
+Options:
+
+-h, --help           This help message.
+--help-all           This same help message but with additional options.
+--optimized          Use this option to achieve an optimal startup time if you have previously
+                       built a server image using the 'build' command.
+
+Storage (Experimental):
+
+--storage <type>     Experimental: Sets the default storage mechanism for all areas. Possible
+                       values are: jpa, chm, hotrod, file.
+--storage-area-auth-session <type>
+                     Experimental: Sets a storage mechanism for authentication sessions. Possible
+                       values are: jpa, chm, hotrod, file.
+--storage-area-authorization <type>
+                     Experimental: Sets a storage mechanism for authorizations. Possible values
+                       are: jpa, chm, hotrod, file.
+--storage-area-client <type>
+                     Experimental: Sets a storage mechanism for clients. Possible values are: jpa,
+                       chm, hotrod, file.
+--storage-area-client-scope <type>
+                     Experimental: Sets a storage mechanism for client scopes. Possible values are:
+                       jpa, chm, hotrod, file.
+--storage-area-event-admin <type>
+                     Experimental: Sets a storage mechanism for admin events. Possible values are:
+                       jpa, chm, hotrod, file.
+--storage-area-event-auth <type>
+                     Experimental: Sets a storage mechanism for authentication and authorization
+                       events. Possible values are: jpa, chm, hotrod, file.
+--storage-area-group <type>
+                     Experimental: Sets a storage mechanism for groups. Possible values are: jpa,
+                       chm, hotrod, file.
+--storage-area-login-failure <type>
+                     Experimental: Sets a storage mechanism for login failures. Possible values
+                       are: jpa, chm, hotrod, file.
+--storage-area-realm <type>
+                     Experimental: Sets a storage mechanism for realms. Possible values are: jpa,
+                       chm, hotrod, file.
+--storage-area-role <type>
+                     Experimental: Sets a storage mechanism for roles. Possible values are: jpa,
+                       chm, hotrod, file.
+--storage-area-single-use-object <type>
+                     Experimental: Sets a storage mechanism for single use objects. Possible values
+                       are: jpa, chm, hotrod.
+--storage-area-user <type>
+                     Experimental: Sets a storage mechanism for users. Possible values are: jpa,
+                       chm, hotrod, file.
+--storage-area-user-session <type>
+                     Experimental: Sets a storage mechanism for user and client sessions. Possible
+                       values are: jpa, chm, hotrod, file.
+--storage-deployment-state-version-seed <type>
+                     Experimental: Secret that serves as a seed to mask the version number of
+                       Keycloak in URLs. Need to be identical across all servers in the cluster.
+                       Will default to a random number generated when starting the server which is
+                       secure but will lead to problems when a loadbalancer without sticky sessions
+                       is used or nodes are restarted.
+--storage-file-dir <dir>
+                     Experimental: Root directory for file map store.
+--storage-hotrod-host <host>
+                     Experimental: Sets the host of the Infinispan server.
+--storage-hotrod***
+                     Experimental: Sets the password of the Infinispan user.
+--storage-hotrod-port <port>
+                     Experimental: Sets the port of the Infinispan server.
+--storage-hotrod-username <username>
+                     Experimental: Sets the username of the Infinispan user.
+--storage-jpa-db <type>
+                     Experimental: The database vendor for jpa map storage. Possible values are:
+                       postgres, cockroach. Default: postgres.
+
+Database:
+
+--db <vendor>        The database vendor. Possible values are: dev-file, dev-mem, mariadb, mssql,
+                       mysql, oracle, postgres. Default: dev-file.
+--db-driver <driver> The fully qualified class name of the JDBC driver. If not set, a default
+                       driver is set accordingly to the chosen database.
+--db***
+                     The password of the database user.
+--db-pool-initial-size <size>
+                     The initial size of the connection pool.
+--db-pool-max-size <size>
+                     The maximum size of the connection pool. Default: 100.
+--db-pool-min-size <size>
+                     The minimal size of the connection pool.
+--db-schema <schema> The database schema to be used.
+--db-url <jdbc-url>  The full database JDBC URL. If not provided, a default URL is set based on the
+                       selected database vendor. For instance, if using 'postgres', the default
+                       JDBC URL would be 'jdbc:postgresql://localhost/keycloak'.
+--db-url-database <dbname>
+                     Sets the database name of the default JDBC URL of the chosen vendor. If the
+                       `db-url` option is set, this option is ignored.
+--db-url-host <hostname>
+                     Sets the hostname of the default JDBC URL of the chosen vendor. If the
+                       `db-url` option is set, this option is ignored.
+--db-url-port <port> Sets the port of the default JDBC URL of the chosen vendor. If the `db-url`
+                       option is set, this option is ignored.
+--db-url-properties <properties>
+                     Sets the properties of the default JDBC URL of the chosen vendor. Make sure to
+                       set the properties accordingly to the format expected by the database
+                       vendor, as well as appending the right character at the beginning of this
+                       property value. If the `db-url` option is set, this option is ignored.
+--db-username <username>
+                     The username of the database user.
+
+Transaction:
+
+--transaction-xa-enabled <true|false>
+                     If set to false, Keycloak uses a non-XA datasource in case the database does
+                       not support XA transactions. Default: true.
+
+Feature:
+
+--features <feature> Enables a set of one or more features. Possible values are: account-api,
+                       account2, account3, admin-api, admin-fine-grained-authz, admin2,
+                       authorization, ciba, client-policies, client-secret-rotation,
+                       declarative-user-profile, docker, dynamic-scopes, fips, impersonation,
+                       js-adapter, kerberos, map-storage, par, preview, recovery-codes, scripts,
+                       step-up-authentication, token-exchange, update-email, web-authn.
+--features-disabled <feature>
+                     Disables a set of one or more features. Possible values are: account-api,
+                       account2, account3, admin-api, admin-fine-grained-authz, admin2,
+                       authorization, ciba, client-policies, client-secret-rotation,
+                       declarative-user-profile, docker, dynamic-scopes, fips, impersonation,
+                       js-adapter, kerberos, map-storage, par, preview, recovery-codes, scripts,
+                       step-up-authentication, token-exchange, update-email, web-authn.
+
+Config:
+
+--config-keystore <config-keystore>
+                     Specifies a path to the KeyStore Configuration Source.
+--config-keystore***
+                     Specifies a password to the KeyStore Configuration Source.
+--config-keystore-type <config-keystore-type>
+                     Specifies a type of the KeyStore Configuration Source. Default: PKCS12.
+
+Logging:
+
+--log <handler>      Enable one or more log handlers in a comma-separated list. Possible values
+                       are: console, file, gelf. Default: console.
+--log-console-color <true|false>
+                     Enable or disable colors when logging to console. Default: false.
+--log-console-format <format>
+                     The format of unstructured console log entries. If the format has spaces in
+                       it, escape the value using "<format>". Default: %d{yyyy-MM-dd HH:mm:ss,SSS} %
+                       -5p [%c] (%t) %s%e%n.
+--log-console-output <output>
+                     Set the log output to JSON or default (plain) unstructured logging. Possible
+                       values are: default, json. Default: default.
+--log-file <file>    Set the log file path and filename. Default: data/log/keycloak.log.
+--log-file-format <format>
+                     Set a format specific to file log entries. Default: %d{yyyy-MM-dd HH:mm:ss,
+                       SSS} %-5p [%c] (%t) %s%e%n.
+--log-file-output <output>
+                     Set the log output to JSON or default (plain) unstructured logging. Possible
+                       values are: default, json. Default: default.
+--log-gelf-facility <name>
+                     The facility (name of the process) that sends the message. Default: keycloak.
+--log-gelf-host <hostname>
+                     Hostname of the Logstash or Graylog Host. By default UDP is used, prefix the
+                       host with 'tcp:' to switch to TCP. Example: 'tcp:localhost' Default:
+                       localhost.
+--log-gelf-include-location <true|false>
+                     Include source code location. Default: true.
+--log-gelf-include-message-parameters <true|false>
+                     Include message parameters from the log event. Default: true.
+--log-gelf-include-stack-trace <true|false>
+                     If set to true, occuring stack traces are included in the 'StackTrace' field
+                       in the GELF output. Default: true.
+--log-gelf-level <level>
+                     The log level specifying which message levels will be logged by the GELF
+                       logger. Message levels lower than this value will be discarded. Default:
+                       INFO.
+--log-gelf-max-message-size <size>
+                     Maximum message size (in bytes). If the message size is exceeded, GELF will
+                       submit the message in multiple chunks. Default: 8192.
+--log-gelf-port <port>
+                     The port the Logstash or Graylog Host is called on. Default: 12201.
+--log-gelf-timestamp-format <pattern>
+                     Set the format for the GELF timestamp field. Uses Java SimpleDateFormat
+                       pattern. Default: yyyy-MM-dd HH:mm:ss,SSS.
+--log-level <category:level>
+                     The log level of the root category or a comma-separated list of individual
+                       categories and their levels. For the root category, you don't need to
+                       specify a category. Default: info.
+
+Export:
+
+--dir <dir>          Set the path to a directory where files will be created with the exported data.
+--file <file>        Set the path to a file that will be created with the exported data. To export
+                       more than 500 users, export to a directory with different files instead.
+--realm <realm>      Set the name of the realm to export. If not set, all realms are going to be
+                       exported.
+--users <strategy>   Set how users should be exported. Possible values are: skip, realm_file,
+                       same_file, different_files. Default: different_files.
+--users-per-file <number>
+                     Set the number of users per file. It is used only if 'users' is set to
+                       'different_files'. Increasing this number leads to exponentially increasing
+                       export times. Default: 50.

docs/documentation/server_admin/topics/export-import.adoc

@@ -1,124 +0,0 @@
-
-[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.
-
-Admin Console import does not preserve IDs. When you import a resource, {project_name} generates a new ID for the resource.
-This behavior is different from the export/import of the full database mechanism described previously.
-
-[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.
-====

docs/guides/server/importExport.adoc

@@ -8,6 +8,14 @@
 
 In this {section}, you are going to understand the different approaches for importing and exporting realms using JSON files.
 
+[NOTE]
+====
+Exporting and importing 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.
+Using a directory performs better 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.
+Increasing this to a larger number leads to an exponentially increasing execution time.
+====
+
 == Providing options for database connection parameters
 
 When using the `export` and the `import` commands below, Keycloak needs to know how to connect to the database where the information about realms, clients, users and other entities is stored.

quarkus/config-api/src/main/java/org/keycloak/config/ExportOptions.java

@@ -21,7 +21,7 @@ public class ExportOptions {
 
     public static final Option<String> FILE = new OptionBuilder<>("file", String.class)
             .category(OptionCategory.EXPORT)
-            .description("Set the path to a file that will be created with the exported data.")
+            .description("Set the path to a file that will be created with the exported data. To export more than 500 users, export to a directory with different files instead.")
             .buildTime(false)
             .build();
 
@@ -40,7 +40,7 @@ public class ExportOptions {
     public static final Option<Integer> USERS_PER_FILE = new OptionBuilder<>("users-per-file", Integer.class)
             .category(OptionCategory.EXPORT)
             .defaultValue(50)
-            .description("Set the number of users per file. It is used only if 'users' is set to 'different_files'.")
+            .description("Set the number of users per file. It is used only if 'users' is set to 'different_files'. Increasing this number leads to exponentially increasing export times.")
             .buildTime(false)
             .build();
 

quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testExportHelp.unix.approved.txt

@@ -131,11 +131,13 @@ Logging:
 Export:
 
 --dir <dir>          Set the path to a directory where files will be created with the exported data.
---file <file>        Set the path to a file that will be created with the exported data.
+--file <file>        Set the path to a file that will be created with the exported data. To export
+                       more than 500 users, export to a directory with different files instead.
 --realm <realm>      Set the name of the realm to export. If not set, all realms are going to be
                        exported.
 --users <strategy>   Set how users should be exported. Possible values are: skip, realm_file,
                        same_file, different_files. Default: different_files.
 --users-per-file <number>
                      Set the number of users per file. It is used only if 'users' is set to
-                       'different_files'. Default: 50.
+                       'different_files'. Increasing this number leads to exponentially increasing
+                       export times. Default: 50.

quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testExportHelpAll.unix.approved.txt

@@ -194,11 +194,13 @@ Logging:
 Export:
 
 --dir <dir>          Set the path to a directory where files will be created with the exported data.
---file <file>        Set the path to a file that will be created with the exported data.
+--file <file>        Set the path to a file that will be created with the exported data. To export
+                       more than 500 users, export to a directory with different files instead.
 --realm <realm>      Set the name of the realm to export. If not set, all realms are going to be
                        exported.
 --users <strategy>   Set how users should be exported. Possible values are: skip, realm_file,
                        same_file, different_files. Default: different_files.
 --users-per-file <number>
                      Set the number of users per file. It is used only if 'users' is set to
-                       'different_files'. Default: 50.
+                       'different_files'. Increasing this number leads to exponentially increasing
+                       export times. Default: 50.