Chapter 13. Datasource Management With Agroal

13.1. About the Agroal Datasources Subsystem

A new datasources-agroal subsystem was introduced in JBoss EAP 7.2. This is a new high performance direct connection pool backed by the Agroal project. This can be used as an alternative to the current JCA-based datasources subsystem.

The datasources-agroal subsystem is not available by default and you must enable it in order to use this new implementation.

Important

The datasources-agroal subsystem is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

13.2. Enabling the Agroal Datasources Subsystem

The datasources-agroal subsystem is not enabled in the default JBoss EAP configuration. Use the following management CLI commands to enable it.

  1. Add the extension.

    /extension=org.wildfly.extension.datasources-agroal:add
  2. Add the subsystem.

    /subsystem=datasources-agroal:add
  3. Reload the server for the changes to take effect.

    reload

This adds the following XML in the server configuration file.

<server xmlns="urn:jboss:domain:8.0">
  <extensions>
    ...
    <extension module="org.wildfly.extension.datasources-agroal"/>
    ...
  </extensions>
  ...
  <subsystem xmlns="urn:jboss:domain:datasources-agroal:1.0"/>
  ...
</server>

13.3. Installing a JDBC Driver as a Core Module for Agroal Datasources

Before defining Agroal datasources in JBoss EAP for your applications to use, you must first install the appropriate JDBC driver.

To install a JDBC driver as a core module for Agroal datasources, you must first add the JDBC driver as a core module and then register the JDBC driver in the datasources-agroal subsystem.

13.3.1. Add the JDBC Driver as a Core Module

JDBC drivers can be installed as a core module using the management CLI using the following steps.

  1. Download the JDBC driver.

    Download the appropriate JDBC driver from your database vendor. See JDBC Driver Download Locations for standard download locations for JDBC drivers of common databases.

    Make sure to extract the archive if the JDBC driver JAR file is contained within a ZIP or TAR archive.

  2. Start the JBoss EAP server.
  3. Launch the management CLI.

    $ EAP_HOME/bin/jboss-cli.sh
  4. Use the module add management CLI command to add the new core module.

    module add --name=MODULE_NAME --resources=PATH_TO_JDBC_JAR --dependencies=DEPENDENCIES

    For example, the following command adds a MySQL JDBC driver module.

    module add --name=com.mysql --resources=/path/to/mysql-connector-java-8.0.12.jar --dependencies=javax.api,javax.transaction.api
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

    Execute module --help for more details on using this command to add and remove modules.

You must next register it as a JDBC driver for it to be referenced by application datasources.

13.3.2. Register the JDBC Driver for Agroal Datasources

After the driver has been installed as a core module, you must register it as a JDBC driver using the following management CLI command. When running in a managed domain, be sure to precede this command with /profile=PROFILE_NAME.

/subsystem=datasources-agroal/driver=DRIVER_NAME:add(module=MODULE_NAME,class=CLASS_NAME)

The CLASS_NAME must be a fully qualified class name that implements either java.sql.Driver or javax.sql.DataSource for non-XA datasources, or javax.sql.XADataSource for XA datasources.

13.4. Configuring Agroal Non-XA Datasources

Important

The use of Agroal datasources is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

13.4.1. Create an Agroal Datasource

The following management CLI command creates an Agroal datasource. When running in a managed domain, be sure to precede this command with /profile=PROFILE_NAME.

/subsystem=datasources-agroal/datasource=DATASOURCE_NAME:add(jndi-name=JNDI_NAME,connection-factory={driver=DRIVER_NAME,url=URL},connection-pool={max-size=MAX_POOL_SIZE})

For a complete listing of all available Agroal datasource attributes, see the Agroal Datasource Attributes section.

See Example MySQL Agroal Datasource for an example Agroal datasource configuration.

13.4.2. Remove an Agroal Datasource

The following management CLI command removes an Agroal datasource. When running in a managed domain, be sure to precede this command with /profile=PROFILE_NAME.

/subsystem=datasources-agroal/datasource=DATASOURCE_NAME:remove

13.5. Configuring Agroal XA Datasources

Important

The use of Agroal datasources is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

13.5.1. Create an Agroal XA Datasource

The following management CLI command creates an Agroal XA datasource. When running in a managed domain, be sure to precede this command with /profile=PROFILE_NAME.

/subsystem=datasources-agroal/xa-datasource=XA_DATASOURCE_NAME:add(jndi-name=JNDI_NAME,connection-factory={driver=DRIVER_NAME,connection-properties={ServerName=HOST_NAME,PortNumber=PORT,DatabaseName=DATABASE_NAME}},connection-pool={max-size=MAX_POOL_SIZE})

For a complete listing of all available Agroal datasource attributes, see the Agroal Datasource Attributes section.

See Example MySQL Agroal XA Datasource for an example Agroal XA datasource configuration.

13.5.2. Remove an Agroal XA Datasource

The following management CLI command removes an Agroal XA datasource. When running in a managed domain, be sure to precede this command with /profile=PROFILE_NAME.

/subsystem=datasources-agroal/xa-datasource=DATASOURCE_NAME:remove

13.6. Example Agroal Datasource Configurations

13.6.1. Example MySQL Agroal Datasource

This is an example of a MySQL Agroal datasource configuration with connection and basic security settings.

Example: MySQL Agroal Datasource Configuration
<subsystem xmlns="urn:jboss:domain:datasources-agroal:1.0">
    <datasource name="ExampleAgroalDS" jndi-name="java:jboss/datasources/ExampleAgroalDS">
        <connection-factory driver="mysql" url="jdbc:mysql://localhost:3306/jbossdb" username="admin" password="admin"/>
        <connection-pool max-size="30"/>
    </datasource>
    <drivers>
        <driver name="mysql" module="com.mysql" class="com.mysql.cj.jdbc.Driver"/>
    </drivers>
</subsystem>
Example: MySQL JDBC Driver module.xml File
<?xml version='1.0' encoding='UTF-8'?>

<module xmlns="urn:jboss:module:1.1" name="com.mysql">

    <resources>
        <resource-root path="mysql-connector-java-8.0.12.jar"/>
    </resources>

    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>
Example Management CLI Commands

This example configuration can be achieved by using the following management CLI commands.

  1. Add the MySQL JDBC driver as a core module.

    module add --name=com.mysql --resources=/path/to/mysql-connector-java-8.0.12.jar --dependencies=javax.api,javax.transaction.api
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the MySQL JDBC driver.

    /subsystem=datasources-agroal/driver=mysql:add(module=com.mysql,class=com.mysql.cj.jdbc.Driver)
  3. Add the MySQL datasource.

    /subsystem=datasources-agroal/datasource=ExampleAgroalDS:add(jndi-name=java:jboss/datasources/ExampleAgroalDS,connection-factory={driver=mysql,url=jdbc:mysql://localhost:3306/jbossdb,username=admin,password=admin},connection-pool={max-size=30})

13.6.2. Example MySQL Agroal XA Datasource

This is an example of a MySQL Agroal XA datasource configuration with XA datasource properties and basic security settings.

Example: MySQL Agroal XA Datasource Configuration
<subsystem xmlns="urn:jboss:domain:datasources-agroal:1.0">
    <xa-datasource name="ExampleAgroalXADS" jndi-name="java:jboss/datasources/ExampleAgroalXADS">
        <connection-factory driver="mysqlXA" username="admin" password="admin">
            <connection-properties>
                <property name="ServerName" value="localhost"/>
                <property name="PortNumber" value="3306"/>
                <property name="DatabaseName" value="jbossdb"/>
            </connection-properties>
        </connection-factory>
        <connection-pool max-size="30"/>
    </xa-datasource>
    <drivers>
        <driver name="mysqlXA" module="com.mysql" class="com.mysql.cj.jdbc.MysqlXADataSource"/>
    </drivers>
</subsystem>
Example: MySQL JDBC Driver module.xml File
<?xml version='1.0' encoding='UTF-8'?>

<module xmlns="urn:jboss:module:1.1" name="com.mysql">

    <resources>
        <resource-root path="mysql-connector-java-8.0.12.jar"/>
    </resources>

    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>
Example Management CLI Commands

This example configuration can be achieved by using the following management CLI commands.

  1. Add the MySQL JDBC driver as a core module.

    module add --name=com.mysql --resources=/path/to/mysql-connector-java-8.0.12.jar --dependencies=javax.api,javax.transaction.api
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the MySQL XA JDBC driver.

    /subsystem=datasources-agroal/driver=mysqlXA:add(module=com.mysql,class=com.mysql.cj.jdbc.MysqlXADataSource)
  3. Add the MySQL XA datasource.

    /subsystem=datasources-agroal/xa-datasource=ExampleAgroalXADS:add(jndi-name=java:jboss/datasources/ExampleAgroalXADS,connection-factory={driver=mysqlXA,connection-properties={ServerName=localhost,PortNumber=3306,DatabaseName=jbossdb},username=admin,password=admin},connection-pool={max-size=30})