Create a datasource with a driver module using CLI in JBoss EAP

Solution Verified - Updated

Environment

  • Red Hat JBoss Enterprise Application Platform (EAP)
    • 6.x
    • 7.x
    • 8.x

Issue

  • Create datasources using the command line interface (CLI)
  • Create datasources for Domain configuration using CLI

Resolution

The following is an example for Oracle, but the syntax is valid for other databases as well.

1. Create a module for the JDBC driver

NOTE Module creation is a file system operation. This has special implications for domain configurations and may be a less desirable approach in many scenarios. If using a JDBC driver that consists of a single JAR, a simple JAR based deployment (i.e. in the deployments directory) is usually recommended/preferred to module based configuration.

  • Start EAP, then start the CLI but do not "connect" to the running instance/domain.

    • In standalone mode, the module command will work when connected.
    • In domain mode, when connected, the module command is not available as it's not designed to work with remote host controllers. Modules must be added host by host, using the local unconnected CLI.

  • Use the module add command to deploy the driver as a module (which may include one or more JAR files and may specify a set of dependencies)

    # Additional dependencies may be required depending on the requirements of the driver and application
module add --name=com.oracle.jdbc --resources=/path/to/ojdbc8.jar --dependencies=javax.api,javax.transaction.api
    • The above command must be performed explicitly for every host that uses any profile in the domain where the driver will be registered and used to create datasources. Because subsequent steps to configure the domain (below) are performed across all hosts using a given profile, driver registration and datasource creation (for a profile) will fail if any running host using the profile does not have the driver module already deployed. If JVMs are started later on a host which does not have the module, but which have datasources in its profile that require access to the driver, deployment of the datasources in the JVM will fail at startup.
    • If you create the module manually in the file system (e.g. creating the directory path com/oracle/jdbc/main in the EAP modules directory and adding the module.xml and driver JAR(s)) you will not use the CLI command. Note that the module name in the module.xml must correspond to the directory path to main (e.g. for com/oracle/jdbc/main - where main is the default "slot" - the module name in the module.xml must be com.oracle.jdbc).

2. Register the module as a JDBC driver

  • Run the connect command to connect to the running standalone instance or to the domain to complete driver registration and datasource creation.

  • For domain configurations, prefix the commands below with a specific profile (e.g. /profile=your_profile).

  • Register the driver (this creates a driver entry in the profile which pairs a driver name with the module which includes the JDBC driver JAR and specifies its dependencies).

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

  • Verify the driver

    /subsystem=datasources/jdbc-driver=oracle:read-resource

3. Create a data source.

  • For domain configurations, prefix the commands below with a specific profile (e.g. /profile=your_profile).

  • Create the datasource and set required properties

    # Simple non-XA datasource
/subsystem=datasources/data-source=OracleDS:add(jndi-name="java:jboss/datasources/oracleDS",connection-url="jdbc:oracle:thin:@myoraclehost:1521:MYSID",driver-name=oracle,user-name=jboss,password=jboss,validate-on-match=true,valid-connection-checker-class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker",exception-sorter-class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter")

  • Review configured/configurable values

    /subsystem=datasources/data-source=OracleDS:read-resource
/subsystem=datasources/data-source=OracleDS:read-resource-description

  • The below may be used to change previously configured properties of a datasource (e.g. the password).

    /subsystem=datasources/data-source=OracleDS:write-attribute(name=password,value=123)

    • Note Not all attributes are writeable.

    • See the EAP 7.4 configuration guide or the EAP 6.4 configuration guide for additional information.

    • If passwords contain quotation marks (e.g. "example#), they may be escaped as shown below.

      /subsystem=datasources/data-source=OracleDS:write-attribute(name=password,value="\"example#")

  • Enable the new datasource on the running server.

    /subsystem=datasources/data-source=OracleDS:enable(persistent=true)

  • Some database drivers (Oracle type-2 OCI driver for example) require native libraries in the system path.

    • Environment variables may be set for standalone configurations in the JBOSS_HOME/bin/standalone.conf to address such cases (e.g. LD_LIBRARY_PATH=/path/to/libs).

    • For domain configurations, do not add environment variables to the domain.conf. Instead add to the JVM environment variables.

      /host=master/jvm=default:write-attribute(name=environment-variables,value={ "LD_LIBRARY_PATH" => "/path/to/libs"})

    • Repeat the above for each host where the driver may be used.

    • It is also possible to add environment-variables to individual JVM's on the server level.

Diagnostic Steps

Use test-connection to verify that a datasource is working properly.

  • For standalone configurations

    /subsystem=datasources/data-source=OracleDS:test-connection-in-pool

  • For domain configurations

    /host=master/server=server-one/subsystem=datasources/data-source=OracleDS:test-connection-in-pool
    • NOTE: Pools need to be tested in specific JVMs. This requires specification of the host and server name for domain configurations.
SBR
Product(s)
Components
Category
Tags

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.