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 Jakarta Connectors-based datasources
subsystem.
The datasources-agroal
subsystem is not available by default and you must enable it in order to use this new implementation.
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.
Add the extension.
/extension=org.wildfly.extension.datasources-agroal:add
Add the subsystem.
/subsystem=datasources-agroal:add
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.
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.
- Start the JBoss EAP server.
Launch the management CLI.
$ EAP_HOME/bin/jboss-cli.sh
Use the
module add
management CLI command to add the new core module.[disconnected /] module add --name=MODULE_NAME --resources=PATH_TO_JDBC_JAR --dependencies=DEPENDENCIES
Example
The following command adds a MySQL JDBC driver module:
[disconnected /] module add --name=com.mysql --resources=/path/to/mysql-connector-java-8.0.12.jar --dependencies=javax.transaction.api,sun.jdk,ibm.jdk,javaee.api,javax.api
Example
To launch the management CLI and add a new core module in a single step, use the following command:
$ EAP_HOME/bin/jboss-cli.sh --command="module add --name=MODULE_NAME --resources=PATH_TO_JDBC_JAR --dependencies=DEPENDENCIES"
ImportantUsing 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
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
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="javaee.api"/> <module name="sun.jdk"/> <module name="ibm.jdk"/> <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.
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=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
ImportantUsing 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.
Register the MySQL JDBC driver.
/subsystem=datasources-agroal/driver=mysql:add(module=com.mysql,class=com.mysql.cj.jdbc.Driver)
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="javaee.api"/> <module name="sun.jdk"/> <module name="ibm.jdk"/> <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.
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=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
ImportantUsing 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.
Register the MySQL XA JDBC driver.
/subsystem=datasources-agroal/driver=mysqlXA:add(module=com.mysql,class=com.mysql.cj.jdbc.MysqlXADataSource)
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})