Configuring Agroal Datasource on WildFly

WildFly 14 has been released. One of the most interesting features of it is the new Agroal Datasource. Agroal is a datasource connection pool implementation with integration with transaction, security and other systems.

In a nutshell, the advantage over the standard connection pool (provided by the datasources subsystem) is that it does not use the JCA implementation which enables you to reach a broader range of heterogenuous Enterprise Information Systems (EIP). The downside of the default JCA-based datasource is that it’s more heavyweight solution when you are merely using connections towards a relational database only.

As you might imagine, the advantage of using a “direct” database connection pool is an improved performance in terms of SQL Execution. Agroal Datasource however is not intended to be used only for plain SQL statements, but it can be used as well as a replacement for JPA based application, by specifying an Agroal Datasource rather than a standard datasource:

<persistence-unit name="agroal-pu">
   <description>Agroal Datasource in persistence.xml</description>
   <jta-data-source>java:jboss/datasources/myagroaldatasource</jta-data-source>
</persistence-unit>

Configuring the Agroal Datasource

Let’s see in practice how to configure Agroal Datasource. In WildFly 14, the Agroal Datasource is not yet the default datasource therefore you need to add at first the available extension to your configuration. Launch the jboss-cli.sh script, connect and execute:

/extension=org.wildfly.extension.datasources-agroal:add

Next, we will add the datasources-agroal subsystem itself to your model:

/subsystem=datasources-agroal:add

In future releases of the application server the datasources-agroal extension and its subsystem will be added by default so check with your configuration if they are already there!

Ok, now we will configure an agroal datasource. With the current release of the application server, this is possible only by adding the driver as a module so let’s add it. We will use a Dockerized Postgresql as an example:

module add --name=agroalds --dependencies=javax.api,javax.transaction.api --resources=/tmp/postgresql-42.2.2.jar

Reload your configuration:

reload

Now it’s time to add a JDBC Driver to your datasource-agroal configuration:

/subsystem=datasources-agroal/driver=agroal_driver:add(class=org.postgresql.Driver,module=agroalds)

Last step, is adding a new agroal-datasource with the following CLI command:

/subsystem=datasources-agroal/datasource=AgroalDataSource:add(jndi-name=java:jboss/datasources/AgroalDatasource,connection-factory={driver=agroal_driver,username=postgres,password=postgres,url=jdbc:pgsql://172.17.0.2:5432/postgres},statistics-enabled=true,connection-pool={min-size=1,max-size=20})

As you can see from the above command, the only requirement is to define an Agroal Connection factory with a reference to the JDBC Driver, the username and password and, at least, a connection pool size.

This will reflect in the following XML datasource:

<subsystem xmlns="urn:jboss:domain:datasources-agroal:1.0">
    <datasource name="AgroalDataSource" jndi-name="java:jboss/datasources/AgroalDatasource" statistics-enabled="true">
        <connection-factory driver="agroal_driver" url="jdbc:pgsql://172.17.0.2:5432/postgres" username="postgres" password="postgres"/>
        <connection-pool max-size="20" min-size="1"/>
    </datasource>
    <drivers>
        <driver name="agroal_driver" module="agroalds" class="org.postgresql.Driver"/>
    </drivers>
</subsystem>

Configuring an Agroal XA Datasource

If your transactions involve more than one resource manager, you can still use agroal as replacement for the standard xa-datasource. The difference is that you will be adding as driver an XA Provider:

/subsystem=datasources-agroal/driver=xa_agroal_driver:add(class=org.postgresql.xa.PGXADataSource,module=agroalds)

Then you will add an xa-datasource, pretty much the same way you did for the non-xa datasource:

/subsystem=datasources-agroal/xa-datasource=XAAgroalDataSource:add(jndi-name=java:jboss/datasources/XAAgroalDatasource,connection-factory={driver=xa_agroal_driver,username=postgres,password=postgres,url=jdbc:pgsql://172.17.0.2:5432/postgres},statistics-enabled=true,connection-pool={min-size=1,max-size=10})

And here is the resulting configuration for the XA Datasource:

<subsystem xmlns="urn:jboss:domain:datasources-agroal:1.0">
    <xa-datasource name="XAAgroalDataSource" jndi-name="java:jboss/datasources/XAAgroalDatasource" statistics-enabled="true">
        <connection-factory driver="xa_agroal_driver" url="jdbc:pgsql://172.17.0.2:5432/postgres" username="postgres" password="postgres"/>
        <connection-pool max-size="10" min-size="1"/>
    </xa-datasource>
    <drivers>
        <driver name="xa_agroal_driver" module="agroalds" class="org.postgresql.xa.PGXADataSource"/>
    </drivers>
</subsystem>

WildFly Administration Guide

This article is an excerpt from “WildFly Administration Guide“, the only book which is always updated with the newest features of the application server!

Found the article helpful? if so please follow us on Socials