Defining a JavaEE DataSource in your WAR file

In a previous article, I walked through adding MySQL’s JDBC driver into WildFly. This seems to be the preferred way of using JDBC Drivers and defining DataSources for your applications. The advantage this has is that it abstracts the location of the data from your application and it allows the administrator of WildFly to upgrade JDBC Drivers and databases without the need of rebuilding and redeploying your application. However, as a developer, this might not work for you if you don’t have direct access to your application server.

If you’d rather define your own data source and deploy your own JDBC drivers, there is a way to do this, at least with WildFly. It is deprecated, so it may be removed in future versions. But as of WildFly 14, it still works.

Introducing the -ds.xml file

The first thing you’ll need to do is add your JDBC driver as a project dependency. If you’re using Maven, you can update your pom file as follows:

...
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.12</version>
</dependency>
...

After that, you need to create a <prefix>-ds.xml file. The prefix can be anything you want. The location is exteremely important. Inside of your war file, it must be within <root>/WEB-INF. If you’re using a standard Maven war project configuration, it needs to be located in your /src/main/webapp/WEB-INF folder. Inside of this -ds.xml file you’ll need the following:

<datasources xmlns="http://www.jboss.org/ironjacamar/schema">
    <datasource jndi-name="java:jboss/datasources/exampleDS" pool-name="exampleDS">
        <driver>embedded-mysql.war_com.mysql.cj.jdbc.Driver_8_0</driver>
        <connection-url>jdbc:mysql://10.0.0.129:3306/example?useSSL=false&amp;serverTimezone=UTC</connection-url>
        <security>
            <user-name>exampleuser</user-name>
            <password>password</password>
        </security>
    </datasource>
</datasources>

There are many more options available for you within this file. You can find these described within the schema here. If you’d like to see other examples, you can view them here.

An important note is the “driver” value. Since we’re deploying the driver along with our application, it’s a bit wonky. The format of the name is “<project name with extension>_<driver name>_<major/minor driver version>”.

Outside of that, your persistence.xml file is the same as if you were using a Datasource defined within WildFly itself:

<persistence version="2.1" xmlns="http://xmlns.jcp.org/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd">
    <persistence-unit name="examplePU">
        <jta-data-source>java:jboss/datasources/exampleDS</jta-data-source>
        <properties>
            <property name="hibernate.hbm2ddl.auto" value="update"/>
        </properties>
    </persistence-unit>
</persistence>

Once you’ve built your application and deployed it, you should see some log entries similar to the following:

06:33:52,071 INFO  [org.jboss.as.connector.deployers.jdbc] (MSC service thread 1-5) WFLYJCA0005: Deploying non-JDBC-compliant driver class com.mysql.cj.jdbc.Driver (version 8.0)
06:33:52,095 INFO  [org.jboss.weld.Version] (MSC service thread 1-5) WELD-000900: 3.0.5 (Final)
06:33:52,125 INFO  [org.jboss.as.connector.deployers.jdbc] (MSC service thread 1-3) WFLYJCA0018: Started Driver service with driver-name = embedded-mysql.war_com.mysql.cj.jdbc.Driver_8_0
06:33:52,128 INFO  [org.jboss.as.connector.subsystems.datasources] (MSC service thread 1-2) WFLYJCA0001: Bound data source [ java language=":jboss/datasources/exampleDS"]
06:33:52,128 INFO [org.jboss.as.jpa] (ServerService Thread Pool -- 79) WFLYJPA0010: Starting Persistence Unit (phase 1 of 2) Service 'embedded-mysql.war#examplePU'

Closing

Let me know if you have any questions or problems by leaving a comment below. As mentioned before, this approach to defining your own data source and JDBC driver is marked as deprecated within WildFly so it’s likely to be removed at some point in the future.

Source code is available here: