more
This commit is contained in:
Bill Burke
parent
6f12c15d52
commit
15dee9a196
8 changed files with 226 additions and 53 deletions
|
|
@ -18,6 +18,10 @@
|
||||||
.. link:topics/operating-mode/domain.adoc[Domain Clustered Mode]
|
.. link:topics/operating-mode/domain.adoc[Domain Clustered Mode]
|
||||||
. link:topics/manage.adoc[Managing Config at Runtime]
|
. link:topics/manage.adoc[Managing Config at Runtime]
|
||||||
. link:topics/database.adoc[Relational Database Setup]
|
. link:topics/database.adoc[Relational Database Setup]
|
||||||
|
.. link:topics/checklist.adoc[Setup Checklist]
|
||||||
|
.. link:topics/jdbc.adoc[JDBC Setup]
|
||||||
|
.. link:topics/datasource.adoc[Datasource Setup]
|
||||||
|
.. link:topics/hibernate.adoc[Hibernate Configuration]
|
||||||
{% if book.community %}
|
{% if book.community %}
|
||||||
. link:topics/mongo.adoc[Mongo DB Setup]
|
. link:topics/mongo.adoc[Mongo DB Setup]
|
||||||
{% endif %}
|
{% endif %}
|
||||||
|
|
|
||||||
|
|
@ -36,7 +36,7 @@
|
||||||
"name": "Hibernate",
|
"name": "Hibernate",
|
||||||
"version": "???",
|
"version": "???",
|
||||||
"admindoc": {
|
"admindoc": {
|
||||||
"name": "Hibernate Config",
|
"name": "JBoss Development Guide",
|
||||||
"link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Development_Guide/sect-Java_Persistence_API_JPA.html#sect-Configuration2"
|
"link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Development_Guide/sect-Java_Persistence_API_JPA.html#sect-Configuration2"
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,62 +1,23 @@
|
||||||
[[_database]]
|
[[_database]]
|
||||||
|
|
||||||
== Relational Database Setup
|
== Relational Database Setup
|
||||||
|
{{book.project.name}} comes with its own embedded Java-based relational database called H2.
|
||||||
|
This is the default database that {{book.project.name}} will use to persist data and really only exists so that you can run the authentication
|
||||||
|
server out of the box. We highly recommend that you replace it with a more production ready external database. The H2 database
|
||||||
|
is not very viable in high concurrency situations and cannot be used in a cluster either. The purpose of this chapter is to
|
||||||
|
show you how to connect {{book.project.name}} to a more mature database.
|
||||||
|
|
||||||
Out of the box, {{book.project.name}} persists its data using the Hibernate JPA set of APIs on top of an embedded Java based relational database.
|
{{book.project.name}} uses two layered technologies to persist its relational data. The bottom layered technology is JDBC. JDBC
|
||||||
The built-in database is not viable in high load and high concurrency situations. It cannot be used in a cluster either. It is
|
is a Java API that is used to connect to a RDBMS. There are different JDBC drivers per database type that are provided
|
||||||
highly recommended that you replace the default embedded database with a more scalable and reliable solution like PostgreSQL or MySql. This
|
by your database vendor. This chapter discusses how to configure {{book.project.name}} to use one of these vendor-specific drivers.
|
||||||
chapter will show you how to configure {{book.project.name}} to use an external relational database. It will also discuss
|
|
||||||
how you can configure the Hibernate JPA persistence abstraction that sits on top of your RDBMS.
|
|
||||||
|
|
||||||
NOTE: Datasource configuration is covered much more thoroughly within the link:{{book.appserver.dataource.link}}[the datasource configuration chapter]
|
The top layered technology for persistence is Hibernate JPA. This is a object to relational mapping API that maps Java
|
||||||
|
Objects to relational data. Most deployments of {{book.project.name}} will never have to touch the configuration aspects
|
||||||
|
of Hibernate, but we will discuss how that is done if you run into that rare circumstance.
|
||||||
|
|
||||||
|
NOTE: Datasource configuration is covered much more thoroughly within the link:{{book.appserver.datasource.link}}[the datasource configuration chapter]
|
||||||
of the {{book.appserver.admindoc.name}}.
|
of the {{book.appserver.admindoc.name}}.
|
||||||
|
|
||||||
=== RDBMS Checklist
|
|
||||||
|
|
||||||
These are the steps you will need to perform to get an RDBMS configured for {{book.project.name}}.
|
|
||||||
|
|
||||||
. Locate and download a JDBC driver for your database
|
|
||||||
. Package the driver JAR into a module and install this module into the server
|
|
||||||
. Declare the JDBC driver in the configuration profile of the server
|
|
||||||
. Modify the datasource configuration to use your database's JDBC driver
|
|
||||||
. Modify the datasource configuration to define the connection parameters to your database
|
|
||||||
|
|
||||||
This chapter will use PostgresSQL for all its examples. Other databases follow the same steps for installation.
|
|
||||||
|
|
||||||
=== Package the JDBC Driver
|
|
||||||
|
|
||||||
Find and download the JDBC driver JAR for your RDBMS. Before you can use this driver, you must package it up into a module.
|
|
||||||
Modules define JARs that are loaded into the {{book.project.name}} classpath and the dependencies those JARs have on
|
|
||||||
other modules. They are pretty simple to set up.
|
|
||||||
|
|
||||||
Within the _.../modules/system/layers/keycloak/_ directory of your
|
|
||||||
{{book.project.name}} distribution, you need to create a directory structure to hold your module definition. The convention is use the Java package name
|
|
||||||
of the JDBC driver for the name of the directory structure. For PostgreSQL, create the directory _org/postgresql/main_. Copy your database
|
|
||||||
driver JAR into this directory and also create an empty _module.xml_ file.
|
|
||||||
|
|
||||||
.Module Directory
|
|
||||||
image:../{{book.images}}/db-module.png[]
|
|
||||||
|
|
||||||
After you have done this, open up the _module.xml_ file and create the following XML
|
|
||||||
|
|
||||||
.Module XML
|
|
||||||
[source,xml]
|
|
||||||
----
|
|
||||||
<?xml version="1.0" ?>
|
|
||||||
<module xmlns="urn:jboss:module:1.3" name="org.postgresql">
|
|
||||||
|
|
||||||
<resources>
|
|
||||||
<resource-root path="postgresql-9.4.1208.jar"/>
|
|
||||||
</resources>
|
|
||||||
|
|
||||||
<dependencies>
|
|
||||||
<module name="javax.api"/>
|
|
||||||
<module name="javax.transaction.api"/>
|
|
||||||
</dependencies>
|
|
||||||
</module>
|
|
||||||
----
|
|
||||||
|
|
||||||
The module name should match the directory structure of your module. _org/postgresql_ maps to +org.postgresql+. The
|
|
||||||
+resource-root path+ attribute should specify the JAR filename. The rest are just the normal dependencies that
|
|
||||||
any JDBC driver JAR would have.
|
|
||||||
|
|
||||||
|
|
|
||||||
12
topics/database/checklist.adoc
Executable file
12
topics/database/checklist.adoc
Executable file
|
|
@ -0,0 +1,12 @@
|
||||||
|
=== RDBMS Setup Checklist
|
||||||
|
|
||||||
|
These are the steps you will need to perform to get an RDBMS configured for {{book.project.name}}.
|
||||||
|
|
||||||
|
. Locate and download a JDBC driver for your database
|
||||||
|
. Package the driver JAR into a module and install this module into the server
|
||||||
|
. Declare the JDBC driver in the configuration profile of the server
|
||||||
|
. Modify the datasource configuration to use your database's JDBC driver
|
||||||
|
. Modify the datasource configuration to define the connection parameters to your database
|
||||||
|
|
||||||
|
This chapter will use PostgresSQL for all its examples. Other databases follow the same steps for installation.
|
||||||
|
|
||||||
46
topics/database/datasource.adoc
Executable file
46
topics/database/datasource.adoc
Executable file
|
|
@ -0,0 +1,46 @@
|
||||||
|
=== Modify the {{book.project.name}} Datasource
|
||||||
|
|
||||||
|
After declaring your JDBC driver, you have to modify the existing datasource configuration that {{book.project.name}} uses
|
||||||
|
to connect to the built-in embedded database. You'l need to change it to connect to your new external database. You'll do
|
||||||
|
this within the same configuration file and XML block that you registered your JDBC driver. Here's an example
|
||||||
|
that set's up the connection to your new database:
|
||||||
|
|
||||||
|
.Declare Your JDBC Drivers
|
||||||
|
[source,xml]
|
||||||
|
----
|
||||||
|
<subsystem xmlns="urn:jboss:domain:datasources:4.0">
|
||||||
|
<datasources>
|
||||||
|
...
|
||||||
|
<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true">
|
||||||
|
<connection-url>jdbc:postgresql://localhost/keycloak</connection-url>
|
||||||
|
<driver>postgresql</driver>
|
||||||
|
<pool>
|
||||||
|
<max-pool-size>20</max-pool-size>
|
||||||
|
</pool>
|
||||||
|
<security>
|
||||||
|
<user-name>William</user-name>
|
||||||
|
<password>password</password>
|
||||||
|
</security>
|
||||||
|
</datasource>
|
||||||
|
...
|
||||||
|
</datasources>
|
||||||
|
</subsystem>
|
||||||
|
----
|
||||||
|
|
||||||
|
Search for the +datasource+ definition for +KeycloakDS+. You'll first need to specify the +connection-url+. The
|
||||||
|
documentation for your vendor's JDBC implementation will tell you the connection URL you should provide there.
|
||||||
|
|
||||||
|
Next define the +driver+ you will use. This is the logical name of the JDBC driver you declared in the previous section of this
|
||||||
|
chapter.
|
||||||
|
|
||||||
|
It is expensive to open a new connection to a database ever time you want to perform a transaction. To compensate, the datasource
|
||||||
|
implementation maintains a pool of open connections. The +max-pool-size+ specifies the maximum number of connections it will pool.
|
||||||
|
You may want to change the value of this depending on the load of your system.
|
||||||
|
|
||||||
|
Finally, or PostgreSQL at least, you need to define the database username and password that is needed to connect to the database. You
|
||||||
|
may be worried that this is in clear text in the example. There are methods to obfuscate this, but this is beyond the
|
||||||
|
scope of this guide.
|
||||||
|
|
||||||
|
NOTE: For more information and details features of datasources, please see the link:{{book.appserver.datasource.link}}[the datasource configuration chapter]
|
||||||
|
of the {{book.appserver.admindoc.name}}.
|
||||||
|
|
||||||
52
topics/database/hibernate.adoc
Executable file
52
topics/database/hibernate.adoc
Executable file
|
|
@ -0,0 +1,52 @@
|
||||||
|
=== Hibernate Configuration
|
||||||
|
|
||||||
|
The Hibernate persistence API is already pre-configured out of the box. It is rare to have to modify the configuration for it.
|
||||||
|
To configure Hibernate, you need to edit the _keycloak-server.json_ file. If you are running
|
||||||
|
in standalone mode, this file is in the _.../standalone/configuration_ directory. If you are running in domain mode
|
||||||
|
this file will live in the _.../domain/servers/{server name}/configuration_ directory.
|
||||||
|
|
||||||
|
.Hibernate JPA Config
|
||||||
|
[source,json]
|
||||||
|
----
|
||||||
|
"connectionsJpa": {
|
||||||
|
"default": {
|
||||||
|
"dataSource": "java:jboss/datasources/KeycloakDS",
|
||||||
|
"databaseSchema": "update"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
----
|
||||||
|
|
||||||
|
Possible configuration options are:
|
||||||
|
|
||||||
|
dataSource::
|
||||||
|
JNDI name of the dataSource
|
||||||
|
|
||||||
|
jta::
|
||||||
|
boolean property to specify if datasource is JTA capable
|
||||||
|
|
||||||
|
driverDialect::
|
||||||
|
Value of database dialect.
|
||||||
|
In most cases you don't need to specify this property as dialect will be autodetected by Hibernate.
|
||||||
|
|
||||||
|
databaseSchema::
|
||||||
|
Specify if schema should be updated or validated.
|
||||||
|
Valid values are +update+ (default) and +validate+. The +update+ value will set up or update
|
||||||
|
the table definitions that {{book.project.name}} needs. +validate+ just makes sure that the database has
|
||||||
|
the appropriate table definitions set up.
|
||||||
|
|
||||||
|
showSql::
|
||||||
|
Specify whether Hibernate should show all SQL commands in the console (false by default). This is very verbose!
|
||||||
|
|
||||||
|
formatSql::
|
||||||
|
Specify whether Hibernate should format SQL commands (true by default)
|
||||||
|
|
||||||
|
globalStatsInterval::
|
||||||
|
Will log global statistics from Hibernate about executed DB queries and other things.
|
||||||
|
Statistics are always reported to server log at specified interval (in seconds) and are cleared after each report.
|
||||||
|
|
||||||
|
schema::
|
||||||
|
Specify the database schema to use
|
||||||
|
|
||||||
|
NOTE: All these configuration switches and more are described in the link:{{book.jpa.link}}[the Hibernate chapter]
|
||||||
|
of {{book.jpa.name}}.
|
||||||
|
|
||||||
96
topics/database/jdbc.adoc
Executable file
96
topics/database/jdbc.adoc
Executable file
|
|
@ -0,0 +1,96 @@
|
||||||
|
=== Package the JDBC Driver
|
||||||
|
|
||||||
|
Find and download the JDBC driver JAR for your RDBMS. Before you can use this driver, you must package it up into a module.
|
||||||
|
Modules define JARs that are loaded into the {{book.project.name}} classpath and the dependencies those JARs have on
|
||||||
|
other modules. They are pretty simple to set up.
|
||||||
|
|
||||||
|
Within the _.../modules/system/layers/keycloak/_ directory of your
|
||||||
|
{{book.project.name}} distribution, you need to create a directory structure to hold your module definition. The convention is use the Java package name
|
||||||
|
of the JDBC driver for the name of the directory structure. For PostgreSQL, create the directory _org/postgresql/main_. Copy your database
|
||||||
|
driver JAR into this directory and also create an empty _module.xml_ file.
|
||||||
|
|
||||||
|
.Module Directory
|
||||||
|
image:../../{{book.images}}/db-module.png[]
|
||||||
|
|
||||||
|
After you have done this, open up the _module.xml_ file and create the following XML
|
||||||
|
|
||||||
|
.Module XML
|
||||||
|
[source,xml]
|
||||||
|
----
|
||||||
|
<?xml version="1.0" ?>
|
||||||
|
<module xmlns="urn:jboss:module:1.3" name="org.postgresql">
|
||||||
|
|
||||||
|
<resources>
|
||||||
|
<resource-root path="postgresql-9.4.1208.jar"/>
|
||||||
|
</resources>
|
||||||
|
|
||||||
|
<dependencies>
|
||||||
|
<module name="javax.api"/>
|
||||||
|
<module name="javax.transaction.api"/>
|
||||||
|
</dependencies>
|
||||||
|
</module>
|
||||||
|
----
|
||||||
|
|
||||||
|
The module name should match the directory structure of your module. So, _org/postgresql_ maps to +org.postgresql+. The
|
||||||
|
+resource-root path+ attribute should specify the JAR filename. The rest are just the normal dependencies that
|
||||||
|
any JDBC driver JAR would have.
|
||||||
|
|
||||||
|
=== Declare and Load JDBC Driver
|
||||||
|
|
||||||
|
The next thing you have to do is declare your newly packaged JDBC driver into your deployment profile so that it loads and becomes
|
||||||
|
available. Where you perform this action depends on your <<fake/operating-mode.adoc#_operating-mode,operating mode>>. If you're
|
||||||
|
deploying in standard mode, edit _.../standalone/configuration/standalone.xml_. If you're deploying in standard clustering
|
||||||
|
mode, edit _.../standalone/configuration/standalone-ha.xml_. If you're deploying in domain mode, edit
|
||||||
|
_.../domain/configuration/domain.xml_. In domain mode, you'll need to make sure you edit the profile you are using:
|
||||||
|
+auth-server-standalone+ or +auth-server-clustered+
|
||||||
|
|
||||||
|
.Domain Profile
|
||||||
|
[source,xml]
|
||||||
|
----
|
||||||
|
<profile name="auth-server-clustered">
|
||||||
|
...
|
||||||
|
</profile>
|
||||||
|
----
|
||||||
|
|
||||||
|
Within the profile, search for the +drivers+ XML block within the +datasources+ subsystem. You should see
|
||||||
|
a pre-defined driver declared for the H2 JDBC driver. There is where you'll declare the JDBC driver for your external
|
||||||
|
database.
|
||||||
|
|
||||||
|
.JDBC Drivers
|
||||||
|
[source,xml]
|
||||||
|
----
|
||||||
|
<subsystem xmlns="urn:jboss:domain:datasources:4.0">
|
||||||
|
<datasources>
|
||||||
|
...
|
||||||
|
<drivers>
|
||||||
|
<driver name="h2" module="com.h2database.h2">
|
||||||
|
<xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
|
||||||
|
</driver>
|
||||||
|
</drivers>
|
||||||
|
</datasources>
|
||||||
|
</subsystem>
|
||||||
|
----
|
||||||
|
|
||||||
|
Within the +drivers+ XML block you'll need to declare an additional JDBC driver. It needs to have a +name+ which
|
||||||
|
you can choose to be anything you want. You have to define the module the new JDBC driver classes are defined in. Finally
|
||||||
|
you have to specify the driver's Java class. Here's an example of installing PostgreSQL driver that lives in the module
|
||||||
|
example defined earlier in this chapter.
|
||||||
|
|
||||||
|
|
||||||
|
.Declare Your JDBC Drivers
|
||||||
|
[source,xml]
|
||||||
|
----
|
||||||
|
<subsystem xmlns="urn:jboss:domain:datasources:4.0">
|
||||||
|
<datasources>
|
||||||
|
...
|
||||||
|
<drivers>
|
||||||
|
<driver name="postgresql" module="org.postgresql">
|
||||||
|
<xa-datasource-class>org.postgresql.Driver</xa-datasource-class>
|
||||||
|
</driver>
|
||||||
|
<driver name="h2" module="com.h2database.h2">
|
||||||
|
<xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
|
||||||
|
</driver>
|
||||||
|
</drivers>
|
||||||
|
</datasources>
|
||||||
|
</subsystem>
|
||||||
|
----
|
||||||
|
|
@ -1,3 +1,5 @@
|
||||||
|
[[_operating_mode]]
|
||||||
|
|
||||||
== Choosing an Operating Mode
|
== Choosing an Operating Mode
|
||||||
|
|
||||||
Before deploying {{book.project.name}} in a production environment you need to decide which type of operating mode
|
Before deploying {{book.project.name}} in a production environment you need to decide which type of operating mode
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue