keycloak-scim/server_installation/topics/database/jdbc.adoc

=== Packaging 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 and install it into the server. Modules define JARs that are loaded into the {project_name} classpath and the dependencies those JARs have on other modules. 

.Procedure

. Create a directory structure to hold your module definition within the _.../modules/_ directory of your {project_name} distribution.
+
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 create an empty _module.xml_ file within it too.
+
.Module Directory
image:{project_images}/db-module.png[Module Directory]

. Open up the _module.xml_ file and create the following XML:
+
.Module XML
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.3" name="org.postgresql">

    <resources>
        <resource-root path="postgresql-VERSION.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 of the driver.
* The rest are just the normal dependencies that any JDBC driver JAR would have.

=== Declaring and loading the JDBC driver

You declare your JDBC into your deployment profile so that it loads and becomes available when the server boots up.

.Prerequisites

You have packaged the JDBC driver.

.Procedure

. Declare your JDBC driver by editing one of these files based on your deployment mode:

* For standalone mode, edit _.../standalone/configuration/standalone.xml_.
* For standalone clustering mode, edit _.../standalone/configuration/standalone-ha.xml_.
* For domain mode, edit _.../domain/configuration/domain.xml_.
+
In domain mode, make sure you edit the profile you are using: either `auth-server-standalone` or `auth-server-clustered`

. 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. This is where you'll declare the JDBC driver for your external database.
+
.JDBC Drivers
[source,xml,subs="attributes+"]
----
  <subsystem xmlns="{subsystem_datasources_xml_urn}">
     <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, declare an additional JDBC driver.

* Assign any `name` to this driver.
* Specify the `module` attribute which points to the `module` package that you created earlier for the driver JAR.
* Specify the driver's Java class.
+
Here's an example of installing a PostgreSQL driver that lives in the module example defined earlier in this chapter.
+
.Declare Your JDBC Drivers
[source,xml,subs="attributes+"]
----
  <subsystem xmlns="{subsystem_datasources_xml_urn}">
     <datasources>
       ...
       <drivers>
          <driver name="postgresql" module="org.postgresql">
              <xa-datasource-class>org.postgresql.xa.PGXADataSource</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>
----