keycloak-scim/topics/database/jdbc.adoc

=== 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>
----