Running multiple versions of database drivers in JBoss EAP

Resolution

Note for JBoss EAP 6: Please make sure the latest patches are applied

• Multiple JDBC drivers versions - wrong driver is used is resolved in JBoss EAP 6.4 cumulative patch 2 (6.4.2) and later
• JDBC driver module-slot is not persisted in domain mode is resolved in JBoss EAP 6.4 cumulative patch 3 (6.4.3) and later

Directions after patching

When creating a module for the driver, you can specify a slot for it
The default slot is main

The below uses Oracle for the examples, but the syntax is the same for other databases.
The commands (other then the module command) are for standalone mode. For domain mode, simply prefix them with /profile=yourprofile

Start the CLI, but do not connect. For domain mode this will need to be done on each host controller.

Install the default driver:

module add --name=com.oracle.jdbc --resources=/path/to/ojdbc6_11.2.0.3.jar --dependencies=javax.api,javax.transaction.api

Add a specific version to it's private slot - we're using the slot "appX" to indicate this is used by application X (but the name is free to choose of course)

module add --name=com.oracle.jdbc --resources=/path/to/ojdbc6_11.2.0.2.0.jar --slot=appX --dependencies=javax.api,javax.transaction.api

For reference, this results in the directory structure:

modules/com/oracle/jdbc/
├── main
│   ├── module.xml
│   └── ojdbc6_11.2.0.3.jar
└── appX
    ├── module.xml
    └── ojdbc6_11.2.0.2.0.jar

The module.xml for the "appX" will look like this; note the "slot" attribute:

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.oracle.jdbc" slot="appX">
    <resources>
        <resource-root path="ojdbc6_11.2.0.2.0.jar"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>

Next, in the CLI, connect to the standalone instance or to the domain controller.

Register both drivers:

The default one, which will become the "main" slot.

/subsystem=datasources/jdbc-driver=oracle:add(driver-module-name=com.oracle.jdbc,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource,driver-name=oracle)

and the specific one, in the "appX" slot

/subsystem=datasources/jdbc-driver=appX:add(driver-module-name=com.oracle.jdbc,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource,driver-name=appX,module-slot=appX)

For reference, this results in the XML snippet; note the ":appX" suffix to the "module" attribute

<subsystem xmlns="urn:jboss:domain:datasources:1.1">
  <datasources>
...
    <drivers>
      <driver name="oracle" module="com.oracle.jdbc">
        <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
      </driver>
      <driver name="appX" module="com.oracle.jdbc:appX">
        <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
      </driver>
    </drivers>
  </datasources>
</subsystem>

When creating datasource, simply specify if you want to use the "oracle" or the "appX" driver.
Details on setting up datasources can be found in How to create a datasource from the JBoss CLI in JBoss EAP 6

Updated: Feb 2, 2026: for JBoss EAP 7.1 or later

The slot attribute in module.xml has been deprecated since JBoss Modules 1.6 by MODULES-256 Deprecate ModuleIdentifier. JBoss Modules 1.6 has been bundled since JBoss EAP 7.1, and the default version in JBoss EAP 8 is JBoss Modules 2.1.

If you downgrade the XML schema version of module.xml to 1.5 as shown below, the slot attribute is available in JBoss EAP 7.1+ and 8.0+:

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.5" name="com.oracle.jdbc" slot="23.26">
    <resources>
        <resource-root path="ojdbc17.jar"/>
    </resources>
    <dependencies>
      <module name="wildflyee.api"/>
      <module name="java.se"/>
      <module name="java.xml" export="true"/>
      <module name="java.xml.crypto" export="true"/>
      <module name="jdk.xml.dom" export="true"/>
      <module name="jakarta.transaction.api"/>
    </dependencies>
</module>

However, this approach is retained only for backward compatibility. For JBoss EAP 7.1+/8 new installations, it is recommended to use a newer schema version, such as 1.9 in module.xml with JBoss EAP 8, same as the other modules bundled with JBoss EAP 8. For JBoss EAP 8.0+, follow the steps below to set up multiple version of JDBC driver.

The reason for not using the module add command is that, even in JBoss EAP 8.1, module add generates module.xml file with very old schema version 1.1 due to the limitations discussed in WFCORE-5872 CLI command "module add" produces module 1.1 instead of 1.9.

mkdir -p jboss-eap-8.1/modules/com/oracle/jdbc/main
cp /<path-to-jdbc>/ojdbc17.jar jboss-eap-8.1/modules/com/oracle/jdbc/main/
cat <<EOF > jboss-eap-8.1/modules/com/oracle/jdbc/main/module.xml
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.oracle.jdbc">
    <resources>
      <resource-root path="ojdbc17.jar"/>
    </resources>
    <dependencies>
      <module name="wildflyee.api"/>
      <module name="java.se"/>
      <module name="java.xml" export="true"/>
      <module name="java.xml.crypto" export="true"/>
      <module name="jdk.xml.dom" export="true"/>
      <module name="jakarta.transaction.api"/>
    </dependencies>
</module>
EOF

mkdir -p jboss-eap-8.1/modules/com/oracle/jdbc/23.26
cp /<path-to-jdbc>/ojdbc17.jar jboss-eap-8.1/modules/com/oracle/jdbc/main/
cat <<EOF > jboss-eap-8.1/modules/com/oracle/jdbc/23.26/module.xml
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.oracle.jdbc:23.26">
    <resources>
      <resource-root path="ojdbc17.jar"/>
    </resources>
    <dependencies>
      <module name="wildflyee.api"/>
      <module name="java.se"/>
      <module name="java.xml" export="true"/>
      <module name="java.xml.crypto" export="true"/>
      <module name="jdk.xml.dom" export="true"/>
      <module name="jakarta.transaction.api"/>
    </dependencies>
</module>
EOF

The created custom module can be referenced from the datasource subsystem in standalone.xml as shown below:

<subsystem xmlns="urn:jboss:domain:datasources:7.2">
    <datasources>
        <datasource jndi-name="java:jboss/datasources/OracleDS-with-older-driver" pool-name="OracleDS-with-older-driver">
            <connection-url>...</connection-url>
            <driver>oracle-jdbc-23.26</driver>
            ...
        </datasource>
        <datasource jndi-name="java:jboss/datasources/OracleDS-with-newer-driver" pool-name="OracleDS-with-newer-driver">
            <connection-url>...</connection-url>
            <driver>oracle</driver>
            ...
        </datasource>
        <drivers>
            <driver name="oracle-jdbc-23.26" module="com.oracle.jdbc:23.26">
                <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
            </driver>
            <driver name="oracle" module="com.oracle.jdbc">
                <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
            </driver>
        </drivers>
    </datasources>
</subsystem>