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/manage.adoc[Managing Config at Runtime]
|
||||
. 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 %}
|
||||
. link:topics/mongo.adoc[Mongo DB Setup]
|
||||
{% endif %}
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@
|
|||
"name": "Hibernate",
|
||||
"version": "???",
|
||||
"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"
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,62 +1,23 @@
|
|||
[[_database]]
|
||||
|
||||
== 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.
|
||||
The built-in database is not viable in high load and high concurrency situations. It cannot be used in a cluster either. It is
|
||||
highly recommended that you replace the default embedded database with a more scalable and reliable solution like PostgreSQL or MySql. This
|
||||
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.
|
||||
{{book.project.name}} uses two layered technologies to persist its relational data. The bottom layered technology is JDBC. JDBC
|
||||
is a Java API that is used to connect to a RDBMS. There are different JDBC drivers per database type that are provided
|
||||
by your database vendor. This chapter discusses how to configure {{book.project.name}} to use one of these vendor-specific drivers.
|
||||
|
||||
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}}.
|
||||
|
||||
=== 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
|
||||
|
||||
Before deploying {{book.project.name}} in a production environment you need to decide which type of operating mode
|
||||
|
|
|
|||
Loading…
Reference in a new issue