Improve database topic
Improve clarity, readability, and consistency of the database topic Closes: #10012
This commit is contained in:
Martin Kanis
Hynek Mlnařík
parent
e44cea587f
commit
2aadc07703
1 changed files with 52 additions and 42 deletions
|
|
@ -7,15 +7,11 @@
|
|||
summary="An overview about how to configure relational databases"
|
||||
includedOptions="db db-* transaction-xa-enabled">
|
||||
|
||||
In this guide, you are going to understand how to configure the server to store data using different relational databases.
|
||||
You will also learn what databases are supported by the server.
|
||||
This guide explains how to configure the Keycloak server to store data in a relational database.
|
||||
|
||||
== Querying the list of supported databases
|
||||
== Supported databases
|
||||
|
||||
The server has built-in support for different databases. You should be able to query the available databases by looking at the expected values
|
||||
for the `db` configuration option.
|
||||
|
||||
The list of supported databases and their corresponding versions are:
|
||||
The server has built-in support for different databases. You can query the available databases by viewing the expected values for the `db` configuration option. The following table lists the supported databases and their tested versions.
|
||||
|
||||
|===
|
||||
|Database | Tested Version
|
||||
|
|
@ -32,34 +28,38 @@ only exists for development use-cases. The `dev-file` database is not suitable f
|
|||
|
||||
== Configuring a database
|
||||
|
||||
For each supported database, the server provides some opinionated defaults to make it simpler to configure a database. The defaults allow
|
||||
you to easily configure a database by just providing some key settings like the database host and credentials.
|
||||
For each supported database, the server provides some opinionated defaults to simplify database configuration. You complete the configuration by providing some key settings such as the database host and credentials.
|
||||
|
||||
To configure the database vendor, run the `build` command to build a server image using the `db` build option to configure the server for specific database:
|
||||
|
||||
.Configuring a database vendor
|
||||
. Build a server image for your database. For example, for a PostgreSQL database, enter this command:
|
||||
+
|
||||
<@kc.build parameters="--db postgres"/>
|
||||
|
||||
Once the database vendor is set, you can start the server and set the configuration options to configure the database host and credentials:
|
||||
|
||||
.Starting the server
|
||||
. Start the server and set the options for the database host and credentials by entering this command:
|
||||
+
|
||||
<@kc.start parameters="--db-url-host mypostgres --db-username myuser --db-password change_me"/>
|
||||
+
|
||||
This command includes the minimum settings needed to connect to the database.
|
||||
|
||||
These are the bare minimum settings that you need to set in order to successfully connect to a database.
|
||||
The default schema is `keycloak`, but you can change it by using the `db-schema` configuration option.
|
||||
|
||||
By default, the default schema is set to `keycloak`. You can change that by using the `db-schema` configuration option.
|
||||
== Overriding default connection settings
|
||||
|
||||
== Overriding the default connection settings
|
||||
The server uses JDBC as the underlying technology to communicate with the database. If the default connection settings are insufficient, you can specify a JDBC URL using the `db-url` configuration option.
|
||||
|
||||
The server uses JDBC as the underlying technology to communicate with the relational database. In case the default connection settings are not enough, you are able to specify your own JDBC URL using the `db-url` configuration option.
|
||||
The following is a sample command for a PostgreSQL database.
|
||||
|
||||
.Starting the server
|
||||
<@kc.start parameters="--db-url jdbc:postgresql://mypostgres/mydatabase"/>
|
||||
|
||||
Be aware that you need to escape characters when invoking commands containing special shell characters such as `;` using the CLI, so you might want to set it in the configuration file instead.
|
||||
|
||||
== Configuring the database for Unicode
|
||||
== Configuring Unicode support for the database
|
||||
|
||||
Database schema only accounts for Unicode strings in the following special fields:
|
||||
Unicode support for all fields depends on whether the database allows VARCHAR and CHAR fields to use the Unicode character set.
|
||||
|
||||
* If these fields can be set, Unicode is likely to work, usually at the expense of field length.
|
||||
* If the database only supports Unicode in the NVARCHAR and NCHAR fields, Unicode support for all text fields is unlikely to work because the server schema uses VARCHAR and CHAR fields extensively.
|
||||
|
||||
The database schema provides support for Unicode strings only for the following special fields:
|
||||
|
||||
* *Realms*: display name, HTML display name, localization texts (keys and values)
|
||||
|
||||
|
|
@ -73,57 +73,67 @@ Database schema only accounts for Unicode strings in the following special field
|
|||
|
||||
* Descriptions of objects
|
||||
|
||||
Otherwise, characters are limited to those contained in database encoding which is often 8-bit. However, for some database systems, it is possible to enable UTF-8 encoding of Unicode characters and use full Unicode character set in all text fields. Often, this is counterbalanced by shorter maximum length of the strings than in case of 8-bit encodings.
|
||||
Otherwise, characters are limited to those contained in database encoding, which is often 8-bit. However, for some database systems, you can enable UTF-8 encoding of Unicode characters and use the full Unicode character set in all text fields. For a given database, this choice might result in a shorter maximum string length than the maximum string length supported by 8-bit encodings.
|
||||
|
||||
Some of the databases require special settings to database and/or JDBC driver to be able to handle Unicode characters. Please find the settings for your database below. Note that if a database is listed here, it can still work properly provided it handles UTF-8 encoding properly both on the level of database and JDBC driver.
|
||||
=== Configuring Unicode support for an Oracle database
|
||||
|
||||
Technically, the key criterion for Unicode support for all fields is whether the database allows setting of Unicode character set for VARCHAR and CHAR fields. If yes, there is a high chance that Unicode will be plausible, usually at the expense of field length. If it only supports Unicode in NVARCHAR and NCHAR fields, Unicode support for all text fields is unlikely as the server schema uses VARCHAR and CHAR fields extensively.
|
||||
Unicode characters are supported in an Oracle database if the database was created with Unicode support in the VARCHAR and CHAR fields. For example, you configured AL32UTF8 as the database character set. In this case, the JDBC driver requires no special settings.
|
||||
|
||||
=== Oracle database
|
||||
If the database was not created with Unicode support, you need to configure the JDBC driver to support Unicode characters in the special fields. You configure two properties. Note that you can configure these properties as system properties or as connection properties.
|
||||
|
||||
Unicode characters are properly handled provided the database was created with Unicode support in VARCHAR and CHAR fields (e.g. by using AL32UTF8 character set as the database character set). No special settings is needed for JDBC driver.
|
||||
. Set `oracle.jdbc.defaultNChar` to `true`.
|
||||
|
||||
If the database character set is not Unicode, then to use Unicode characters in the special fields, the JDBC driver needs to be configured with the connection property oracle.jdbc.defaultNChar set to true. It might be wise, though not strictly necessary, to also set the oracle.jdbc.convertNcharLiterals connection property to true. These properties can be set either as system properties or as connection properties. Please note that setting oracle.jdbc.defaultNChar may have negative impact on performance. For details, please refer to Oracle JDBC driver configuration documentation.
|
||||
. Optionally, set `oracle.jdbc.convertNcharLiterals` to `true`.
|
||||
+
|
||||
[NOTE]
|
||||
====
|
||||
For details on these properties and any performance implications, see the Oracle JDBC driver configuration documentation.
|
||||
====
|
||||
|
||||
=== Microsoft SQL Server database
|
||||
=== Unicode support for a Microsoft SQL Server database
|
||||
|
||||
Unicode characters are properly handled only for the special fields. No special settings of JDBC driver or database is necessary.
|
||||
Unicode characters are supported only for the special fields for a Microsoft SQL Server database. The JDBC driver and database require no special settings.
|
||||
|
||||
=== MySQL database
|
||||
=== Configuring Unicode support for a MySQL database
|
||||
|
||||
Unicode characters are properly handled provided the database was created with Unicode support in VARCHAR and CHAR fields in the CREATE DATABASE command (e.g. by using utf8 character set as the default database character set in MySQL 5.5. Please note that utf8mb4 character set does not work due to different storage requirements to utf8 character set [1]). Note that in this case, length restriction to non-special fields does not apply because columns are created to accommodate given amount of characters, not bytes. If the database default character set does not allow storing Unicode, only the special fields allow storing Unicode values.
|
||||
Unicode characters are supported in a MySQL database if the database was created with Unicode support in the VARCHAR and CHAR fields when using the CREATE DATABASE command.
|
||||
|
||||
At the side of JDBC driver settings, it is necessary to add a connection property characterEncoding=UTF-8 to the JDBC connection settings.
|
||||
Note that the utf8mb4 character set is not supported due to different storage requirements for the utf8 character set. See MySQL documentation for details. In that situation, the length restriction on non-special fields does not apply because columns are created to accommodate the number of characters, not bytes. If the database default character set does not allow Unicode storage, only the special fields allow storing Unicode values.
|
||||
|
||||
=== PostgreSQL database
|
||||
. Start MySQL Server.
|
||||
. Under JDBC driver settings, locate the *JDBC connection settings*.
|
||||
. Add this connection property: `characterEncoding=UTF-8`
|
||||
|
||||
Unicode is supported when the database character set is UTF8. In that case, Unicode characters can be used in any field, there is no reduction of field length for non-special fields. No special settings of JDBC driver is necessary.
|
||||
=== Configuring Unicode support for a PostgreSQL database
|
||||
|
||||
The character set of a PostgreSQL database is determined at the time it is created. You can determine the default character set for a PostgreSQL cluster with the SQL command
|
||||
Unicode is supported for a PostgreSQL database when the database character set is UTF8. Unicode characters can be used in any field with no reduction of field length for non-special fields. The JDBC driver requires no special settings. The character set is determined when the PostgreSQL database is created.
|
||||
|
||||
. Check the default character set for a PostgreSQL cluster by entering the following SQL command.
|
||||
+
|
||||
```
|
||||
show server_encoding;
|
||||
```
|
||||
|
||||
If the default character set is not UTF 8, then you can create the database with UTF8 as its character set like this:
|
||||
. If the default character set is not UTF 8, create the database with the UTF8 as the default character set using a command such as:
|
||||
|
||||
+
|
||||
```
|
||||
create database keycloak with encoding 'UTF8';
|
||||
```
|
||||
|
||||
== Changing database locking timeout when running in a cluster
|
||||
== Changing database locking timeout in a cluster configuration
|
||||
|
||||
Cluster nodes are allowed to boot concurrently. When the server instance boots up it may do some database migration, importing, or first time initializations. A DB lock is used to prevent start actions from conflicting with one another when cluster nodes boot up concurrently.
|
||||
Because cluster nodes can boot concurrently, they take extra time for database actions. For example, a booting server instance may perform some database migration, importing, or first time initializations. A database lock prevents start actions from conflicting with each other when cluster nodes boot up concurrently.
|
||||
|
||||
By default, the maximum timeout for this lock is 900 seconds. If a node is waiting on this lock for more than the timeout it will fail to boot. Typically you won’t need to increase/decrease the default value, but just in case it’s possible to configure it as follows:
|
||||
The maximum timeout for this lock is 900 seconds. If a node waits on this lock for more than the timeout, the boot fails. The need to change the default value is unlikely, but you can change it by entering this command:
|
||||
|
||||
<@kc.start parameters="--spi-dblock-jpa-lock-wait-timeout 900"/>
|
||||
|
||||
== Using Database Vendors without XA transaction support
|
||||
Keycloak uses XA transactions and the appropriate database drivers by default. There are vendors like Azure SQL and MariaDB Galera, that do not support or rely on the XA transaction mechanism. To use Keycloak without XA transaction support using the appropriate jdbc driver, invoke the following command:
|
||||
Keycloak uses XA transactions and the appropriate database drivers by default. Certain vendors, such as Azure SQL and MariaDB Galera, do not support or rely on the XA transaction mechanism. To use Keycloak without XA transaction support using the appropriate JDBC driver, enter the following command:
|
||||
|
||||
<@kc.build parameters="--db=<vendor> --transaction-xa-enabled=false"/>
|
||||
|
||||
Keycloak will automatically choose the appropriate jdbc driver for your vendor.
|
||||
Keycloak automatically chooses the appropriate JDBC driver for your vendor.
|
||||
|
||||
</@tmpl.guide>
|
||||
|
|
|
|||
Loading…
Reference in a new issue