Chapter 11. Datasource management
11.1. About JBoss EAP datasources
About JDBC
The JDBC API is the standard that defines how databases are accessed by Java applications. An application configures a datasource that references a JDBC driver. Application code can then be written against the driver, rather than the database. The driver converts the code to the database language. This means that if the correct driver is installed, an application can be used with any supported database.
For more information, see the JDBC specification
Supported databases
See JBoss EAP 8.0 supported configurations for the list of JDBC-compliant databases supported by JBoss EAP 8.0.
Datasource types
The two general types of resources are referred to as datasources and XA datasources.
- Non-XA datasources
- Used for applications that do not use transactions, or applications that use transactions with a single database.
- XA datasources
- Used by applications that use multiple databases or other XA resources as part of one XA transaction. XA datasources introduce additional overhead.
You specify which type of datasource to use when creating the datasource using the JBoss EAP management interfaces.
The ExampleDS datasource
JBoss EAP ships with an example datasource configuration, ExampleDS, which is provided to demonstrate how datasources are defined. This datasource uses an H2 database, which is a lightweight, relational database management system that provides developers with the ability to quickly build applications.
The ExampleDS datasource and the H2 database should not be used in a production environment. This is a very small, self-contained datasource that supports all of the standards needed for testing and building applications, but is not robust or scalable enough for production use.
11.2. JDBC drivers
Before defining datasources in JBoss EAP for your applications to use, you must first install the appropriate JDBC driver.
11.2.1. Installing a JDBC driver as a core module
To install a JDBC driver as a core module, you must first add the JDBC driver as a core module and then register the JDBC driver in the datasources
subsystem.
11.2.1.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-j-8.0.33.jar --dependencies=jakarta.transaction.api,java.se,wildflyee.api,java.xml,java.xml.crypto,jdk.xml.dom
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.
11.2.1.2. Register the JDBC driver
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/jdbc-driver=DRIVER_NAME:add(driver-name=DRIVER_NAME,driver-module-name=MODULE_NAME,driver-xa-datasource-class-name=XA_DATASOURCE_CLASS_NAME, driver-class-name=DRIVER_CLASS_NAME)
The driver-class-name
parameter is only required if the JDBC driver jar defines more than one class in its /META-INF/services/java.sql.Driver
file.
For example, the /META-INF/services/java.sql.Driver
file in the MySQL 5.1.36 JDBC driver JAR defines two classes:
- com.mysql.cj.jdbc.Driver
- com.mysql.fabric.jdbc.FabricMySQLDriver
For this case, you would pass in driver-class-name=com.mysql.cj.jdbc.Driver
.
For example, the following command registers a MySQL JDBC driver.
/subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource, driver-class-name=com.mysql.cj.jdbc.Driver)
The JDBC driver is now available to be referenced by application datasources.
11.2.2. Installing a JDBC driver as a JAR deployment
JDBC drivers can be installed as a JAR deployment using either the management CLI or the management console. As long as the driver is JDBC 4-compliant, it will automatically be recognized and installed as a JDBC driver upon deployment.
The following steps describe how to install a JDBC driver using the management CLI.
The recommended installation method for JDBC drivers is to install them as a core module.
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.
- If the JDBC driver is not JDBC 4-compliant, see the steps to Update a JDBC Driver JAR to be JDBC 4-Compliant.
Deploy the JAR to JBoss EAP.
deploy PATH_TO_JDBC_JAR
NoteIn a managed domain, specify the appropriate server groups.
For example, the following command deploys a MySQL JDBC driver.
deploy /path/to/mysql-connector-j-8.0.33.jar
A message will be displayed in the JBoss EAP server log that displays the deployed driver name, which will be used when defining datasources.
WFLYJCA0018: Started Driver service with driver-name = mysql-connector-j-8.0.33.jar
The JDBC driver is now available to be referenced by application datasources.
Update a JDBC driver JAR to be JDBC 4-compliant
If the JDBC driver JAR is not JDBC 4-compliant, it can be made deployable using the following steps.
- Create an empty temporary directory.
-
Create a
META-INF
subdirectory. -
Create a
META-INF/services
subdirectory. Create a
META-INF/services/java.sql.Driver
file and add one line to indicate the fully-qualified class name of the JDBC driver.For example, the below line would be added for a MySQL JDBC driver.
com.mysql.cj.jdbc.Driver
Use the JAR command-line tool to add this new file to the JAR.
jar \-uf jdbc-driver.jar META-INF/services/java.sql.Driver
11.2.3. JDBC driver download locations
The following table gives the standard download locations for JDBC drivers of common databases used with JBoss EAP.
These links point to third-party websites which are not controlled or actively monitored by Red Hat. For the most up-to-date drivers for your database, check your database vendor’s documentation and website.
Vendor | Download Location |
---|---|
MySQL | |
PostgreSQL | |
Oracle | http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html |
IBM | |
Sybase | The jConnect JDBC driver is part of the SDK for SAP ASE installation. Currently there is not a separate download site for this driver by itself. |
Microsoft |
11.2.4. Access vendor-specific classes
In some cases, it is necessary for an application to use vendor-specific functionality that is not part of the JDBC API. In these cases, you can access vendor-specific APIs by declaring a dependency in that application.
This is advanced usage. Only applications that need functionality not found in the JDBC API should implement this procedure.
This process is required when using the reauthentication mechanism, and accessing vendor-specific classes.
You can define a dependency for an application using either the MANIFEST.MF
file or a jboss-deployment-structure.xml
file.
If you have not yet done so, install a JDBC driver as a core module.
Using the MANIFEST.MF
file
-
Edit the application’s
META-INF/MANIFEST.MF
file. Add the
Dependencies
line and specify the module name.For example, the below line declares the
com.mysql
module as a dependency.Dependencies: com.mysql
Using a jboss-deployment-structure.xml
file
-
Create a file called
jboss-deployment-structure.xml
in theMETA-INF/
orWEB-INF/
folder of the application. Specify the module using the
dependencies
element.For example, the following example
jboss-deployment-structure.xml
file declares thecom.mysql
module as a dependency.<jboss-deployment-structure> <deployment> <dependencies> <module name="com.mysql"/> </dependencies> </deployment> </jboss-deployment-structure>
The example code below accesses the MySQL API.
import java.sql.Connection; ... Connection c = ds.getConnection(); if (c.isWrapperFor(com.mysql.jdbc.Connection.class)) { com.mysql.jdbc.Connection mc = c.unwrap(com.mysql.jdbc.Connection.class); }
Follow the vendor-specific API guidelines closely, as the connection is being controlled by the IronJacamar container.
11.3. Creating datasources
Datasources can be created using the management console or the management CLI.
JBoss EAP 8.0 allows you to use expressions in datasource attribute values, such as the enabled
attribute.
11.3.1. Create a non-XA datasource
You can create non-XA datasources using either the management CLI or the management console.
Defining a non-XA datasource using the management console
Navigate to datasources in standalone or domain mode.
Use the following navigation in the standalone mode:
Configuration
Subsystems Datasources & Drivers Datasources Use the following navigation in the domain mode:
Configuration
Profiles full Datasources & Drivers Datasources
- Click the Add (+) button and choose Add Datasource.
- It opens the Add Datasource wizard where you can choose the datasource type and click Next. This creates a template for your database. The following pages of the wizard are prefilled with values specific for the selected datasource. This makes the datasource creation process easy.
- You can test your connection on the Test Connection page before finishing the datasource creation process.
- Review the details and click Finish to create the datasource.
Defining a non-XA datasource using the management CLI
Non-XA datasources can be defined using the data-source add
management CLI command.
- If you have not yet done so, install and register the appropriate JDBC Driver as a Core Module.
Define the datasource using the
data-source add
command, specifying the appropriate argument values.data-source add --name=DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME --connection-url=CONNECTION_URL --user-name=USER_NAME --password=PASSWORD
NoteIn a managed domain, you must specify the
--profile=PROFILE_NAME
argument.See the Datasource Parameters section below for tips on these parameter values.
For detailed examples, see the Example Datasource Configurations for the supported databases.
Datasource parameters
- jndi-name
-
The JNDI name for the datasource must start with
java:/
orjava:jboss/
. For example,java:jboss/datasources/ExampleDS
. - driver-name
The driver name value depends on whether the JDBC driver was installed as a core module or a JAR deployment.
- For a core module, the driver name value will be the name given to the JDBC driver when it was registered.
For a JAR deployment, the driver name is the name of the JAR if there is only one class listed in its
/META-INF/services/java.sql.Driver
file. If there are multiple classes listed, then the value isJAR_NAME
+ "_" +DRIVER_CLASS_NAME
+ "_" +MAJOR_VERSION
+ "_" +MINOR_VERSION
(for examplemysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1
).You can also see the driver name listed in the JBoss EAP server log when the JDBC JAR is deployed.
WFLYJCA0018: Started Driver service with driver-name = mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1
- connection-url
- For details on the connection URL formats for the supported databases, see the list of Datasource Connection URLs.
For a complete listing of all available datasource attributes, see the Datasource Attributes section.
- user-name
- The user name to use when creating a new datasource connection.
- password
- The password to use when creating a new datasource connection.
11.3.2. Create an XA datasource
You can create XA datasources using either the management CLI or the management console.
Defining an XA datasource using the management console
Navigate to datasources in standalone or domain mode.
Use the following navigation in the standalone mode:
Configuration
Subsystems Datasources & Drivers Datasources Use the following navigation in the domain mode:
Configuration
Profiles full Datasources & Drivers Datasources
- Click the Add (+) button and choose Add XA Datasource.
- It opens the Add XA Datasource wizard where you can choose the datasource type and click Next. This creates a template for your database. The following pages of the wizard are prefilled with values specific for the selected datasource. This makes the datasource creation process easy.
- You can test your connection on the Test Connection page before finishing the datasource creation process.
- Review the details and click Finish to create the datasource.
Defining an XA datasource using the management CLI
XA datasources can be defined using the xa-data-source add
management CLI command.
In a managed domain, you will need to specify the profile to use. Depending on the format of the management CLI command, you will either precede the command with /profile=PROFILE_NAME
or pass in the --profile=PROFILE_NAME
argument.
- If you have not yet done so, install and register the appropriate JDBC Driver as a Core Module.
Define the datasource using the
xa-data-source add
command, specifying the appropriate argument values.xa-data-source add --name=XA_DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME --xa-datasource-class=XA_DATASOURCE_CLASS --xa-datasource-properties={"ServerName"=>"HOST_NAME","DatabaseName"=>"DATABASE_NAME"}
See the Datasource Parameters section below for tips on these parameter values.
Set XA datasource properties.
At least one XA datasource property is required when defining an XA datasource or you will receive an error when adding the datasource in the previous step. Any properties that were not set when defining the XA datasource can be set individually afterward.
Set the server name.
/subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=ServerName:add(value=HOST_NAME)
Set the database name.
/subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=DatabaseName:add(value=DATABASE_NAME)
For detailed examples, see the Example Datasource Configurations for the supported databases.
Datasource parameters
- jndi-name
-
The JNDI name for the datasource must start with
java:/
orjava:jboss/
. For example,java:jboss/datasources/ExampleDS
. - driver-name
The driver name value depends on whether the JDBC driver was installed as a core module or a JAR deployment.
- For a core module, the driver name value will be the name given to the JDBC driver when it was registered.
For a JAR deployment, the driver name is the name of the JAR if there is only one class listed in its
/META-INF/services/java.sql.Driver
file. If there are multiple classes listed, then the value isJAR_NAME
+ "_" +DRIVER_CLASS_NAME
+ "_" +MAJOR_VERSION
+ "_" +MINOR_VERSION
, for example,mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1
.You can also see the driver name listed in the JBoss EAP server log when the JDBC JAR is deployed.
WFLYJCA0018: Started Driver service with driver-name = mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1
- xa-datasource-class
-
Specify the XA datasource class for the JDBC driver’s implementation of the
jakarta.sql.XADataSource
class. - xa-datasource-properties
- At least one XA datasource property is required when defining an XA datasource or you will receive an error when attempting to add it. Additional properties can also be added to the XA datasource after it has been defined.
For a complete listing of all available datasource attributes, see the Datasource Attributes section.
11.4. Modifying datasources
Datasources settings can be configured using the management console or the management CLI.
JBoss EAP 8.0 allows you to use expressions in datasource attribute values, such as the enabled
attribute.
11.4.1. Modify a non-XA datasource
Non-XA datasource settings can be updated using the data-source
management CLI command. You can also update datasource
attributes from the management console in standalone or domain mode:
-
In standalone mode, navigate to Configuration
Subsystems Datasources & Drivers Datasources. -
In domain mode, navigate to Configuration
Profiles full Datasources & Drivers Datasources.
Non-XA datasources can be integrated with Jakarta Transactions transactions. To integrate the datasource with Jakarta Transactions, ensure that the jta
parameter is set to true
.
Example of updating settings for a datasource
Settings for a datasource can be updated by using the following management CLI command.
data-source --name=DATASOURCE_NAME --ATTRIBUTE_NAME=ATTRIBUTE_VALUE
In a managed domain, you must specify the --profile=PROFILE_NAME
argument.
A server reload may be required for the changes to take effect.
11.4.2. Modify an XA datasource
XA datasource settings can be updated using the xa-data-source
management CLI command. You can also update datasource
attributes from the management console in standalone or domain mode:
-
In standalone mode, navigate to Configuration
Subsystems Datasources & Drivers Datasources. -
In domain mode, navigate to Configuration
Profiles full Datasources & Drivers Datasources.
Example of updating an XA datasource
Settings for an XA datasource can be updated by using the following management CLI command.
xa-data-source --name=XA_DATASOURCE_NAME --ATTRIBUTE_NAME=ATTRIBUTE_VALUE
NoteIn a managed domain, you must specify the
--profile=PROFILE_NAME
argument.
Example of adding an XA datasource property
An XA datasource property can be added using the following management CLI command.
/subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=PROPERTY:add(value=VALUE)
NoteIn a managed domain, you must precede this command with
/profile=PROFILE_NAME
.
A server reload may be required for the changes to take effect.
11.5. Removing datasources
Datasources can be removed using the management console or the management CLI.
11.5.1. Remove a non-XA datasource
Non-XA datasources can be removed using the data-source remove
management CLI command. You can also use the management console in standalone or domain mode to remove datasources:
-
In standalone mode, navigate to Configuration
Subsystems Datasources & Drivers Datasources. -
In domain mode, navigate to Configuration
Profiles full Datasources & Drivers Datasources.
Use the following command to remove a non-XA datasource:
data-source remove --name=DATASOURCE_NAME
In a managed domain, you must specify the --profile=PROFILE_NAME
argument.
The server will require a reload after the datasource is removed.
11.5.2. Remove an XA datasource
XA datasources can be removed using the xa-data-source remove
management CLI command. You can also use the management console in standalone or domain mode to remove datasources:
-
In standalone mode, navigate to Configuration
Subsystems Datasources & Drivers Datasources. -
In domain mode, navigate to Configuration
Profiles full Datasources & Drivers Datasources.
Use the following command to remove an XA datasource:
xa-data-source remove --name=XA_DATASOURCE_NAME
In a managed domain, you must specify the --profile=PROFILE_NAME
argument.
The server will require a reload after the XA datasource is removed.
11.6. Testing datasource connections
You can use the management CLI or management console to test a datasource connection to verify that its settings are correct.
Test a datasource connection using the management CLI
The following management CLI command can be used to test a datasource’s connection.
/subsystem=datasources/data-source=DATASOURCE_NAME:test-connection-in-pool
In a managed domain, you must precede this command with /host=HOST_NAME/server=SERVER_NAME
. If you are testing an XA datasource, replace data-source=DATASOURCE_NAME
with xa-data-source=XA_DATASOURCE_NAME
.
Test a datasource connection using the management console
When using the Add Datasource wizard in the management console, you have the opportunity to test the connection before creating the datasource. On the Test Connection screen of the wizard, click the Test Connection button.
When a datasource is added, you can test the connection by using the following procedure:
-
Navigate to Configuration
Subsystems Datasources & Drivers Datasources in standalone mode or Configuration Profiles full Datasources & Drivers Datasources in domain mode. - Select the datasource.
- Select Test Connection from the drop-down list.
11.7. Flushing datasource connections
You can flush datasource connections using the following management CLI commands.
In a managed domain, you must precede these commands with /host=HOST_NAME/server=SERVER_NAME
.
Flush all connections in the pool.
/subsystem=datasources/data-source=DATASOURCE_NAME:flush-all-connection-in-pool
Gracefully flush all connections in the pool.
/subsystem=datasources/data-source=DATASOURCE_NAME:flush-gracefully-connection-in-pool
The server will wait until connections become idle before flushing them.
Flush all idle connections in the pool.
/subsystem=datasources/data-source=DATASOURCE_NAME:flush-idle-connection-in-pool
Flush all invalid connections in the pool.
/subsystem=datasources/data-source=DATASOURCE_NAME:flush-invalid-connection-in-pool
The server will flush all connections that it determines to be invalid, for example, by the
valid-connection-checker-class-name
orcheck-valid-connection-sql
validation mechanism discussed in Database Connection Validation.
You can also flush connections using the management console. From the Runtime tab, select the server, select Datasources, choose a datasource, and use the drop down to select the appropriate action.
11.8. XA datasource recovery
An XA datasource is a datasource that can participate in an XA global transaction, which is coordinated by the transaction manager and can span multiple resources in a single transaction. If one of the participants fails to commit its changes, the other participants abort the transaction and restore their state as it was before the transaction occurred. This is to maintain consistency and avoid potential data loss or corruption.
XA recovery is the process of ensuring that all resources affected by a transaction are updated or rolled back, even if any of the resources or transaction participants crash or become unavailable. XA recovery happens without user intervention.
Each XA resource needs to have a recovery module associated with its configuration. The recovery module is the code that is executed when recovery is being performed. JBoss EAP automatically registers recovery modules for JDBC XA resources. You can register a custom module with your XA datasource if you wish to implement custom recovery code. The recovery module must extend class com.arjuna.ats.jta.recovery.XAResourceRecovery
.
11.8.1. Configuring XA recovery
For most JDBC resources, the recovery module is automatically associated with the resource. In these cases, you only need to configure the options that allow the recovery module to connect to your resource to perform recovery.
The following table describes the XA datasource parameters specific to XA recovery. Each of these configuration attributes can be set during datasource creation or afterward. You can set them using either the management console or the management CLI. See Modify an XA Datasource for information on configuring XA datasources.
Attribute | Description |
---|---|
recovery-username | The user name to use to connect to the resource for recovery. Note that if this is not specified, the datasource security settings will be used. |
recovery-password | The password to use to connect to the resource for recovery. Note that if this is not specified, the datasource security settings will be used. |
recovery-security-domain | The security domain to use to connect to the resource for recovery. |
recovery-plugin-class-name |
If you need to use a custom recovery module, set this attribute to the fully-qualified class name of the module. The module should extend class |
recovery-plugin-properties |
If you use a custom recovery module which requires properties to be set, set this attribute to the list of comma-separated |
Disable XA recovery
If multiple XA datasources connect to the same physical database, then XA recovery typically needs to be configured for only one of them.
Use the following management CLI command to disable recovery for an XA datasource:
/subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME:write-attribute(name=no-recovery,value=true)
11.8.2. Vendor-specific XA recovery
Vendor-specific configuration
Some databases require specific configurations in order to cooperate in XA transactions managed by the JBoss EAP transaction manager. For detailed and up-to-date information, see your database vendor’s documentation.
- MySQL
- No special configuration is required. For more information, see the MySQL documentation.
For automated XA recovery, MySQL 8 and later requires special configuration. For more information, see the JBoss EAP 8.0 supported configurations.
- PostgreSQL and Postgres Plus Advanced Server
-
For PostgreSQL to be able to handle XA transactions, change the configuration parameter
max_prepared_transactions
to a value greater than0
and equal to or greater thanmax_connections
. - Oracle
Ensure that the Oracle user,
USER
, has access to the tables needed for recovery.GRANT SELECT ON sys.dba_pending_transactions TO USER; GRANT SELECT ON sys.pending_trans$ TO USER; GRANT SELECT ON sys.dba_2pc_pending TO USER; GRANT EXECUTE ON sys.dbms_xa TO USER;
If the Oracle user does not have the proper permissions, you may see an error such as the following:
WARN [com.arjuna.ats.jta.logging.loggerI18N] [com.arjuna.ats.internal.jta.recovery.xarecovery1] Local XARecoveryModule.xaRecovery got XA exception jakarta.transaction.xa.XAException, XAException.XAER_RMERR
- Microsoft SQL Server
- For more information, see the Microsoft SQL Server documentation, including Understanding XA transactions.
- IBM DB2
- No special configuration is required. For more information, see the IBM DB2 documentation.
- Sybase
Sybase expects XA transactions to be enabled on the database. Without correct database configuration, XA transactions will not work. The
enable xact coordination
parameter enables or disables Adaptive Server transaction coordination services. When this parameter is enabled, Adaptive Server ensures that updates to remote Adaptive Server data commit or roll back with the original transaction.To enable transaction coordination, use:
sp_configure 'enable xact coordination', 1
- MariaDB
- No special configuration is required. For more information, see the MariaDB documentation.
Known issues
These known issues with handling XA transactions are for the specific database and JDBC driver versions supported with JBoss EAP 8.0. For up-to-date information on the supported databases, see JBoss EAP 8.0 supported configurations.
- MySQL
- MySQL is not fully capable of handling XA transactions. If a client is disconnected from MySQL, then all the information about such transactions is lost. See this MySQL bug for more information. Note that this issue was fixed in MySQL 5.7.
- PostgreSQL and Postgres Plus Advanced Server
The JDBC driver returns the
XAER_RMERR
XAException error code when a network failure occurs during the commit phase of two-phase commit (2PC). This error signals an unrecoverable catastrophic event to the transaction manager, but the transaction is left in thein-doubt
state on the database side and could be easily corrected after network connection is established again. The correct return code should beXAER_RMFAIL
orXAER_RETRY
. The incorrect error code causes the transaction to be left in theHeuristic
state on the JBoss EAP side and holding locks in the database which requires manual intervention. See this PostgreSQL bug for more information.If a connection failure happens when the one-phase commit optimization is used, the JDBC driver returns
XAER_RMERR
, but theXAER_RMFAIL
error code should be returned. This could lead to data inconsistency if the database commits data during one-phase commit and the connection goes down at that moment, then the client is informed that transaction was rolled back.The Postgres Plus JDBC driver returns XIDs for all prepared transactions that exist in the Postgres Plus Server, so there is no way to determine the database to which the XID belongs. If you define more than one data source for the same database in JBoss EAP, an in-doubt transaction recovery attempt could be run under wrong account, which causes the recovery to fail.
- Oracle
The JDBC driver returns XIDs belonging to all users on the database instance, when the Recovery Manager calls recovery using datasource configured with some user credentials. The JDBC driver throws the exception
ORA-24774: cannot switch to specified transaction
because it tries to recover XIDs belonging to other users.The workaround for this issue is to grant
FORCE ANY TRANSACTION
privilege to the user whose credentials are used in recovery datasource configuration. For more information about configuring the privilege, see Manually overriding in-doubt transactions.- Microsoft SQL Server
The JDBC driver returns the
XAER_RMERR
XAException error code when a network failure occurs during the commit phase of two-phase commit (2PC). This error signals an unrecoverable catastrophic event to the transaction manager, but the transaction is left in thein-doubt
state on the database side and could be easily corrected after network connection is established again. The correct return code should beXAER_RMFAIL
orXAER_RETRY
. The incorrect error code causes the transaction to be left in theHeuristic
state on the JBoss EAP side and holding locks in the database which requires manual intervention. See this Microsoft SQL Server issue report for more information.If a connection failure happens when the one-phase commit optimization is used, the JDBC driver returns
XAER_RMERR
, but theXAER_RMFAIL
error code should be returned. This could lead to data inconsistency if the database commits data during one-phase commit and the connection goes down at that moment, then the client is informed that transaction was rolled back.- IBM DB2
-
If a connection failure happens during a one-phase commit, the JDBC driver returns
XAER_RETRY
, but theXAER_RMFAIL
error code should be returned. This could lead to data inconsistency if the database commits data during one-phase commit and the connection goes down at that moment, then the client is informed that transaction was rolled back. - Sybase
The JDBC driver returns the
XAER_RMERR
XAException error code when a network failure occurs during the commit phase of two-phase commit (2PC). This error signals an unrecoverable catastrophic event to the transaction manager, but the transaction is left in thein-doubt
state on the database side and could be easily corrected after network connection is established again. The correct return code should beXAER_RMFAIL
orXAER_RETRY
. The incorrect error code causes the transaction to be left in theHeuristic
state on the JBoss EAP side and holding locks in the database which requires manual intervention.If a connection failure happens when the one-phase commit optimization is used, the JDBC driver returns
XAER_RMERR
, but theXAER_RMFAIL
error code should be returned. This could lead to data inconsistency if the database commits data during one-phase commit and the connection goes down at that moment, then the client is informed that transaction was rolled back.If an XA transaction that includes an insert to a Sybase 15.7 or 16 database fails before the Sybase transaction branch is in a prepared state, then repeating the XA transaction and inserting the same record with the same primary key will fail with an error of
com.sybase.jdbc4.jdbc.SybSQLException: Attempt to insert duplicate key row
. This exception will be thrown until the original unfinished Sybase transaction branch is rolled back.- MariaDB
- MariaDB is not fully capable of handling XA transactions. If a client is disconnected from MariaDB, then all the information about such transactions is lost.
- MariaDB Galera Cluster
- XA transactions are not supported in MariaDB Galera Cluster.
11.9. Database connection validation
Database maintenance, network problems, or other outage events may cause JBoss EAP to lose the connection to the database. In order to recover from these situations, you can enable database connection validation for your datasources.
To configure database connection validation, you specify the validation timing method to define when the validation occurs, the validation mechanism to determine how the validation is performed, and the exception sorter to define how exceptions are handled.
Choose one of the validation timing methods.
- validate-on-match
When the
validate-on-match
method is set totrue
, the database connection is validated every time it is checked out from the connection pool using the validation mechanism specified in the next step.If a connection is not valid, a warning is written to the log and the next connection in the pool is retrieved. This process continues until a valid connection is found. If you prefer not to cycle through every connection in the pool, you can use the
use-fast-fail
option. If a valid connection is not found in the pool, a new connection is created. If the connection creation fails, an exception is returned to the requesting application.- background-validation
When the
background-validation
method is set totrue
, connections are validated periodically in a background thread prior to use. The frequency of the validation is specified by thebackground-validation-millis
property. The default value ofbackground-validation-millis
is0
, meaning that it is disabled.When determining the value of the
background-validation-millis
property, consider the following:-
This value should not be set to the same value as your
idle-timeout-minutes
setting. - The lower the value, the more frequently the pool is validated and the sooner invalid connections are removed from the pool.
- Lower values take more database resources. Higher values result in less frequent connection validation checks and use less database resources, but dead connections are undetected for longer periods of time.
-
This value should not be set to the same value as your
NoteThese validation methods are mutually exclusive as demonstrated in the following examples:
-
If
validate-on-match
is set totrue
, you must setbackground-validation
tofalse
. -
If
background-validation
is set totrue
, you must setvalidate-on-match
tofalse
.
For a comparison matrix for these validation methods, see Comparison of validation timing methods.
Choose one of the validation mechanisms.
- valid-connection-checker-class-name
Using
valid-connection-checker-class-name
is the preferred validation mechanism. This specifies a connection checker class that is used to validate connections for the particular database in use. JBoss EAP provides the following connection checkers:-
org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker
-
org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker
-
org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
-
org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker
-
org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker
-
org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker
-
org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker
-
org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
-
org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker
-
- check-valid-connection-sql
Using
check-valid-connection-sql
, you provide the SQL statement that will be used to validate the connection.The following is an example SQL statement that you might use to validate Oracle connections.
select 1 from dual
The following is an example SQL statement that you might use to validate MySQL or PostgreSQL connections.
select 1
Set the exception sorter class name.
When an exception is marked as fatal, the connection is closed immediately, even if the connection is participating in a transaction. Use the exception sorter class option to properly detect and clean up after fatal connection exceptions. Choose the appropriate JBoss EAP exception sorter for your datasource type.
-
org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter
-
org.jboss.jca.adapters.jdbc.extensions.informix.InformixExceptionSorter
-
org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter
-
org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
-
org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter
-
org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
-
org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
-
org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter
-
11.10. Datasource security
Datasource security refers to encrypting or obscuring passwords for datasource connections. These passwords can be stored in plain text in configuration files, but this represents a security risk.
There are several methods you can use for datasource security. Examples of each are included below.
Secure a Datasource using a security domain
Use the following steps to secure a datasource using a security domain:
Create the new security domain.
/subsystem=security/security-domain=DsRealm:add(cache-type=default) /subsystem=security/security-domain=DsRealm/authentication=classic:add(login-modules=[{code=ConfiguredIdentity,flag=required,module-options={userName=sa, principal=sa, password=sa}}])
A security domain for the datasource is defined. The following XML extract is the result of calling CLI commands.
<security-domain name="DsRealm" cache-type="default"> <authentication> <login-module code="ConfiguredIdentity" flag="required"> <module-option name="userName" value="sa"/> <module-option name="principal" value="sa"/> <module-option name="password" value="sa"/> </login-module> </authentication> </security-domain>
Add a new datasource.
data-source add --name=securityDs --jndi-name=java:jboss/datasources/securityDs --connection-url=jdbc:h2:mem:test;DB_CLOSE_DELAY=-1 --driver-name=h2 --new-connection-sql="select current_user()"
Set the security domain on the datasource.
data-source --name=securityDs --security-domain=DsRealm
Reload the server for the changes to be effective.
reload
If you are using a security domain with multiple datasources, disable caching on the security domain. This can be accomplished by setting the value of the cache-type
attribute to none
or by removing the attribute altogether; however, if caching is desired, use a separate security domain for each datasource.
The following XML extract shows the datasource secured with the DsRealm
.
<datasources> <datasource jndi-name="java:jboss/datasources/securityDs" pool-name="securityDs"> <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url> <driver>h2</driver> <new-connection-sql>select current_user()</new-connection-sql> <security> <security-domain>DsRealm</security-domain> </security> </datasource> </datasources>
For more information on using Security Domains, see How to Configure Identity Management.
Secure a datasource using a password vault
Use the following steps to secure a datasource using a password vault:
Set the password vault for the ExampleDS datasource.
data-source --name=ExampleDS --password=${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}
Reload the server to implement the changes.
reload
The following XML security element is added to the ExampleDS datasource secured with password vault.
<security> <user-name>admin</user-name> <password>${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}</password> </security>
For more information on using the Password Vault, see the Password Vault section in the JBoss EAP How to Configure Server Security guide.
Secure a datasource using a credential store
You can also use a credential store to provide passwords. The elytron
subsystem provides the ability to create credential stores to securely house and use your passwords throughout JBoss EAP. You can find more details on creating and using credential stores in the Credential Store section in the JBoss EAP How to Configure Server Security guide.
Adding a credential store reference to ExampleDS
/subsystem=datasources/data-source=ExampleDS:write-attribute(name=credential-reference,value={store=exampleCS, alias=example-ds-pw})
Secure a datasource using an authentication context
You can also use an Elytron authentication context to provide usernames and passwords.
Use the following steps to configure and use an authentication context for datasource security.
Remove
password
anduser-name
./subsystem=datasources/data-source=ExampleDS:undefine-attribute(name=password) /subsystem=datasources/data-source=ExampleDS:undefine-attribute(name=user-name)
Enable Elytron security for the datasource.
/subsystem=datasources/data-source=ExampleDS:write-attribute(name=elytron-enabled,value=true) reload
Create an
authentication-configuration
for your credentials.The authentication configuration contains the credentials you want your datasource to use when making a connection. The below example uses a reference to a credential store, but you could also use an Elytron security domain.
/subsystem=elytron/authentication-configuration=exampleAuthConfig:add(authentication-name=sa,credential-reference={clear-text=sa})
Create an
authentication-context
./subsystem=elytron/authentication-context=exampleAuthContext:add(match-rules=[{authentication-configuration=exampleAuthConfig}])
Update the datasource to use the authentication context.
The below example updates
ExampleDS
to use an authentication context./subsystem=datasources/data-source=ExampleDS:write-attribute(name=authentication-context,value=exampleAuthContext) reload
NoteIf
authentication-context
attribute is not set andelytron-enabled
attribute is set totrue
, JBoss EAP will use the current context for authentication.
Secure a datasource using Kerberos
To secure a datasource using kerberos authentication, the following configuration is required:
- Kerberos is configured on the database server.
- JBoss EAP host server has a keytab entry for the database server.
To secure a datasource using kerberos:
Configure JBoss EAP to use kerberos.
/system-property=java.security.krb5.conf:add(value="/path/to/krb5.conf") /system-property=sun.security.krb5.debug:add(value="false") /system-property=sun.security.spnego.debug:add(value="false")
For debugging, change the values of
sun.security.krb5.debug
andsun.security.spnego.debug
totrue
. In a production environment, it is recommended to set the values tofalse
.Configure security.
You can use legacy security or Elytron security to secure a datasource.
To use kerberos with legacy security:
Configure infinispan cache to periodically remove expired tickets from cache.
batch /subsystem=infinispan/cache-container=security:add(default-cache=auth-cache) /subsystem=infinispan/cache-container=security/local-cache=auth-cache:add() /subsystem=infinispan/cache-container=security/local-cache=auth-cache/expiration=EXPIRATION:add(lifespan=3540000,max-idle=3540000) /subsystem=infinispan/cache-container=security/local-cache=auth-cache/memory=object:add(size=1000) run-batch
The following attributes define ticket expiration:
-
lifespan
: Interval, in milliseconds, at which new certificates are requested from the KDC. Set the value of thelifespan
attribute to be just smaller than the lifespan defined by the KDC. -
max-idle
: Interval, in milliseconds, at which a valid ticket should be removed from the cache, if it unused. -
max-entries
: The maximum number copies of the kerberos tickets to keep in cache. The value corresponds to the number of configured connections in your datasource.
-
Create a security domain.
batch /subsystem=security/security-domain=KerberosDatabase:add(cache-type=infinispan) /subsystem=security/security-domain=KerberosDatabase/authentication=classic:add /subsystem=security/security-domain=KerberosDatabase/authentication=classic/login-module="KerberosDatabase-Module":add(code="org.jboss.security.negotiation.KerberosLoginModule",module="org.jboss.security.negotiation",flag=required, module-options={ "debug" => "false", "storeKey" => "false", "useKeyTab" => "true", "keyTab" => "/path/to/eap.keytab", "principal" => "PRINCIPAL@SERVER.COM", "doNotPrompt" => "true", "refreshKrb5Config" => "true", "isInitiator" => "true", "addGSSCredential" => "true", "credentialLifetime" => "-1"}) run-batch
-
When using Microsoft JDBC driver for SQL server, add attribute and value
"wrapGSSCredential" ⇒ "true"
inmodule-options
. -
For debugging, change the value of the
debug
attribute inmodule-options
totrue
.
-
When using Microsoft JDBC driver for SQL server, add attribute and value
To use kerberos with Elytron:
Set up a kerberos factory in Elytron.
/subsystem=elytron/kerberos-security-factory=krbsf:add(debug=false, principal=PRINCIPAL@SERVER.COM, path=/path/to/keytab, request-lifetime=-1, obtain-kerberos-ticket=true, server=false)
For debugging, add attribute and value
debug = true
.For a list of supported attributes, see the Kerberos Security Factory Attributes section in the How to Configure Server Security guide.
Create an authentication configuration to use the kerberos factory.
/subsystem=elytron/authentication-configuration=kerberos-conf:add(kerberos-security-factory=krbsf)
Create an authentication context.
/subsystem=elytron/authentication-context=ds-context:add(match-rules=[{authentication-configuration=kerberos-conf}])
Secure the datasource with kerberos.
If you use Elytron:
Configure the datasource to use an authentication context.
/subsystem=datasources/data-source=KerberosDS:add(connection-url="URL", min-pool-size=0, max-pool-size=10, jndi-name="java:jboss/datasource/KerberosDS", driver-name=<jdbc-driver>.jar, elytron-enabled=true, authentication-context=ds-context, allow-multiple-users=false, pool-prefill=false, pool-use-strict-min=false, idle-timeout-minutes=2)
Configure vendor-specific connection properties.
/subsystem=datasources/data-source=KerberosDS/connection-properties=<connection-property-name>:add(value="(<kerberos-value>)")
Example: connection properties for Oracle database
/subsystem=datasources/data-source=KerberosDS/connection-properties=oracle.net.authentication_services:add(value="(KERBEROS5)")
When using kerberos authentication, it is recommended to use the following attributes and values for the datasource:
-
pool-prefill=false
-
pool-use-strict-min=false
-
idle-timeout-minutes
For a list of supported attributes, see Datasource Attributes.
11.11. Datasource statistics
When statistics collection is enabled for a datasource, you can view runtime statistics for the datasource.
11.11.1. Enabling datasource statistics
By default, datasource statistics are not enabled. You can enable datasource statistics collection using the management CLI or the management console.
11.11.1.1. Enable datasource statistics using the management CLI
The following management CLI command enables the collection of statistics for the ExampleDS
datasource.
In a managed domain, precede this command with /profile=PROFILE_NAME
.
/subsystem=datasources/data-source=ExampleDS:write-attribute(name=statistics-enabled,value=true)
Reload the server for the changes to take effect.
11.11.1.2. Enable datasource statistics using the management console
Use the following steps to enable statistics collection for a datasource using the management console.
Procedure
Navigate to datasources in standalone or domain mode.
Use the following navigation in the standalone mode:
Configuration
Subsystems Datasources & Drivers Datasources Use the following navigation in the domain mode:
Configuration
Profiles full Datasources & Drivers Datasources
- Select the datasource and click View.
- Click Edit under the Attributes tab.
- Set the Statistics Enabled field to ON and click Save. A popup appears indicating that the changes require a reload in order to take effect.
Reload the server.
- For a standalone server, click the Reload link from the popup to reload the server.
- For a managed domain, click the Topology link from the popup. From the Topology tab, select the appropriate server and select the Reload drop down option to reload the server.
11.11.2. Viewing datasource statistics
You can view runtime statistics for a datasource using the management CLI or management console.
11.11.2.1. View datasource statistics using the management CLI
The following management CLI command retrieves the core pool statistics for the ExampleDS
datasource.
In a managed domain, precede these commands with /host=HOST_NAME/server=SERVER_NAME
.
/subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true) { "outcome" => "success", "result" => { "ActiveCount" => 1, "AvailableCount" => 20, "AverageBlockingTime" => 0L, "AverageCreationTime" => 122L, "AverageGetTime" => 128L, "AveragePoolTime" => 0L, "AverageUsageTime" => 0L, "BlockingFailureCount" => 0, "CreatedCount" => 1, "DestroyedCount" => 0, "IdleCount" => 1, ... }
The following management CLI command retrieves the JDBC statistics for the ExampleDS
datasource.
/subsystem=datasources/data-source=ExampleDS/statistics=jdbc:read-resource(include-runtime=true) { "outcome" => "success", "result" => { "PreparedStatementCacheAccessCount" => 0L, "PreparedStatementCacheAddCount" => 0L, "PreparedStatementCacheCurrentSize" => 0, "PreparedStatementCacheDeleteCount" => 0L, "PreparedStatementCacheHitCount" => 0L, "PreparedStatementCacheMissCount" => 0L, "statistics-enabled" => true } }
Since statistics are runtime information, be sure to specify the `include-runtime=true` argument.
See Datasource Statistics for a detailed list of all available statistics.
11.11.2.2. View datasource statistics using the management console
To view datasource statistics from the management console, navigate to the Datasources subsystem from the Runtime tab, select a datasource, and click View.
See Datasource Statistics for a detailed list of all available statistics.
11.12. Datasource tuning
For tips on monitoring and optimizing performance for the datasources
subsystem, see the Datasource and Resource Adapter Tuning section of the Performance tuning for JBoss EAP.
11.13. Capacity policies
JBoss EAP supports defining capacity policies for Jakarta Connectors deployments, including datasources. Capacity policies define how physical connections for a pool are created, referred to as capacity incrementing, and destroyed, referred to as capacity decrementing. The default policies are set to create one connection per request for capacity incrementing, and destroy all connections when they time out when the idle timeout is scheduled for capacity decrementing.
To configure capacity polices, you need to specify a capacity incrementer class, a capacity decrementer class, or both.
Example: Defining capacity policies
/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-incrementer-class, value="org.jboss.jca.core.connectionmanager.pool.capacity.SizeIncrementer") /subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-decrementer-class, value="org.jboss.jca.core.connectionmanager.pool.capacity.SizeDecrementer")
You can also configure properties on the specified capacity incrementer or decrementer class.
Example: Configuring properties for capacity policies
/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-incrementer-properties.size, value=2) /subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-decrementer-properties.size, value=2)
MaxPoolSize incrementer policy
Class name: org.jboss.jca.core.connectionmanager.pool.capacity.MaxPoolSizeIncrementer
The MaxPoolSize incrementer policy will fill the pool to its max size for each request. This policy is useful when you want to keep the maximum number of connections available all the time.
Size incrementer policy
Class name: org.jboss.jca.core.connectionmanager.pool.capacity.SizeIncrementer
The Size incrementer policy will fill the pool by the specified number of connections for each request. This policy is useful when you want to increment with an additional number of connections per request in anticipation that the next request will also need a connection.
Name | Description |
---|---|
Size | The number of connections that should be created |
This is the default increment policy, and has a size value of 1.
Watermark incrementer policy
Class name: org.jboss.jca.core.connectionmanager.pool.capacity.WatermarkIncrementer
The Watermark incrementer policy will fill the pool to the specified number of connections for each request. This policy is useful when you want to keep a specified number of connections in the pool at all times.
Name | Description |
---|---|
Watermark | The watermark level for the number of connections |
MinPoolSize decrementer policy
Class name: org.jboss.jca.core.connectionmanager.pool.capacity.MinPoolSizeDecrementer
The MinPoolSize decrementer policy will decrement the pool to its minimum size for each request. This policy is useful when you want to limit the number of connections after each idle timeout request. The pool will operate in a First In First Out (FIFO) manner.
Size decrementer policy
Class name: org.jboss.jca.core.connectionmanager.pool.capacity.SizeDecrementer
The Size decrementer policy will decrement the pool by the specified number of connections for each idle timeout request.
Name | Description |
---|---|
Size | The number of connections that should be destroyed |
This policy is useful when you want to decrement an additional number of connections per idle timeout request in anticipation that the pool usage will lower over time.
The pool will operate in a First In First Out (FIFO) manner.
TimedOut decrementer policy
Class name: org.jboss.jca.core.connectionmanager.pool.capacity.TimedOutDecrementer
The TimedOut decrementer policy will remove all connections that have timed out from the pool for each idle timeout request. The pool will operate in a First In Last Out (FILO) manner.
This policy is the default decrement policy.
TimedOut/FIFO decrementer policy
Class name: org.jboss.jca.core.connectionmanager.pool.capacity.TimedOutFIFODecrementer
The TimedOutFIFO decrementer policy will remove all connections that have timed out from the pool for each idle timeout request. The pool will operate in a First In First Out (FIFO) manner.
Watermark decrementer policy
Class name: org.jboss.jca.core.connectionmanager.pool.capacity.WatermarkDecrementer
The Watermark decrementer policy will decrement the pool to the specified number of connections for each idle timeout request. This policy is useful when you want to keep a specified number of connections in the pool at all times. The pool will operate in a First In First Out (FIFO) manner.
Name | Description |
---|---|
Watermark | The watermark level for the number of connections |
11.14. Enlistment tracing
Enlistment traces can be recorded in order to help locate error situations that happen during enlistment of XAResource
instances. When enlistment tracing is enabled, the jca
subsystem creates an exception object for every pool operation, so that an accurate stack trace can be produced if necessary; however, this does come with performance overhead.
As of JBoss EAP 7.1, enlistment tracing is disabled by default. You can enable the recording of enlistment traces for a datasource using the management CLI by setting the enlistment-trace
attribute to true
.
Enable enlistment tracing for a non-XA datasource
data-source --name=DATASOURCE_NAME --enlistment-trace=true
Enable enlistment tracing for an XA datasource
xa-data-source --name=XA_DATASOURCE_NAME --enlistment-trace=true
Enabling enlistment tracing can cause a performance impact.
11.15. Example Datasource Configurations
11.15.1. Example MySQL datasource
This is an example of a MySQL datasource configuration with connection information, basic security, and validation options.
Example: MySQL datasource configuration
<datasources> <datasource jndi-name="java:jboss/MySqlDS" pool-name="MySqlDS"> <connection-url>jdbc:mysql://localhost:3306/jbossdb</connection-url> <driver>mysql</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/> </validation> </datasource> <drivers> <driver name="mysql" module="com.mysql"> <driver-class>com.mysql.cj.jdbc.Driver</driver-class> <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: MySQL JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.mysql"> <resources> <resource-root path="mysql-connector-j-8.0.33.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.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-j-8.0.33.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.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/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource, driver-class-name=com.mysql.cj.jdbc.Driver)
Add the MySQL datasource.
data-source add --name=MySqlDS --jndi-name=java:jboss/MySqlDS --driver-name=mysql --connection-url=jdbc:mysql://localhost:3306/jbossdb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
11.15.2. Example MySQL XA datasource
This is an example of a MySQL XA datasource configuration with XA datasource properties, basic security, and validation options.
Example: MySQL XA datasource configuration
<datasources> <xa-datasource jndi-name="java:jboss/MySqlXADS" pool-name="MySqlXADS"> <xa-datasource-property name="ServerName"> localhost </xa-datasource-property> <xa-datasource-property name="DatabaseName"> mysqldb </xa-datasource-property> <driver>mysql</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/> </validation> </xa-datasource> <drivers> <driver name="mysql" module="com.mysql"> <driver-class>com.mysql.cj.jdbc.Driver</driver-class> <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: MySQL JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.mysql"> <resources> <resource-root path="mysql-connector-j-8.0.33.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.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-j-8.0.33.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.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/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource, driver-class-name=com.mysql.cj.jdbc.Driver)
Add the MySQL XA datasource.
xa-data-source add --name=MySqlXADS --jndi-name=java:jboss/MySqlXADS --driver-name=mysql --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"mysqldb"}
11.15.3. Example PostgreSQL datasource
This is an example of a PostgreSQL datasource configuration with connection information, basic security, and validation options.
Example: PostgreSQL datasource configuration
<datasources> <datasource jndi-name="java:jboss/PostgresDS" pool-name="PostgresDS"> <connection-url>jdbc:postgresql://localhost:5432/postgresdb</connection-url> <driver>postgresql</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"/> </validation> </datasource> <drivers> <driver name="postgresql" module="com.postgresql"> <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: PostgreSQL JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.postgresql"> <resources> <resource-root path="postgresql-42.x.y.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
In the example above, make sure you replace 42.x.y with your driver version number.
Additional resources
- For information about JDBC drivers and how to install them, see JDBC Drivers.
- For information about JDBC drivers that have been tested as part of the JBoss EAP 8.0, see JBoss EAP 8.0 Supported Configurations.
Example management CLI commands
You can add the PostgreSQL JDBC driver and the PostgreSQL datasource to your JDBC API with the following CLI commands.
Add the PostgreSQL JDBC driver as a core module.
module add --name=com.postgresql --resources=/path/to/postgresql-42.x.y.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
In the example above, make sure you replace 42.x.y with your driver version number.
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 PostgreSQL JDBC driver.
/subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=com.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
Add the PostgreSQL datasource.
data-source add --name=PostgresDS --jndi-name=java:jboss/PostgresDS --driver-name=postgresql --connection-url=jdbc:postgresql://localhost:5432/postgresdb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
11.15.4. Example PostgreSQL XA datasource
This is an example of a PostgreSQL XA datasource configuration with XA datasource properties, basic security, and validation options.
Example: PostgreSQL XA datasource configuration
<datasources> <xa-datasource jndi-name="java:jboss/PostgresXADS" pool-name="PostgresXADS"> <xa-datasource-property name="ServerName"> localhost </xa-datasource-property> <xa-datasource-property name="PortNumber"> 5432 </xa-datasource-property> <xa-datasource-property name="DatabaseName"> postgresdb </xa-datasource-property> <driver>postgresql</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"/> </validation> </xa-datasource> <drivers> <driver name="postgresql" module="com.postgresql"> <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: PostgreSQL JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.postgresql"> <resources> <resource-root path="postgresql-42.x.y.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
In the example above, make sure you replace 42.x.y with your driver version number.
Additional resources
- For information about JDBC drivers and how to install them, see JDBC Drivers.
- For information about JDBC drivers that have been tested as part of the JBoss EAP 8.0, see JBoss EAP 8.0 Supported Configurations.
Example management CLI commands
You can add the PostgreSQL JDBC driver and the PostgreSQL datasource to your JDBC API with the following CLI commands.
Add the PostgreSQL JDBC driver as a core module.
module add --name=com.postgresql --resources=/path/to/postgresql-42.x.y.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
In the example above, make sure you replace 42.x.y with your driver version number.
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 PostgreSQL JDBC driver.
/subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=com.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
Add the PostgreSQL XA datasource.
xa-data-source add --name=PostgresXADS --jndi-name=java:jboss/PostgresXADS --driver-name=postgresql --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter --xa-datasource-properties={"ServerName"=>"localhost","PortNumber"=>"5432","DatabaseName"=>"postgresdb"}
11.15.5. Example Oracle datasource
This is an example of an Oracle datasource configuration with connection information, basic security, and validation options.
Example: Oracle datasource configuration
<datasources> <datasource jndi-name="java:jboss/OracleDS" pool-name="OracleDS"> <connection-url>jdbc:oracle:thin:@localhost:1521:XE</connection-url> <driver>oracle</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/> </validation> </datasource> <drivers> <driver name="oracle" module="com.oracle"> <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: Oracle JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.oracle"> <resources> <resource-root path="ojdbc7.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
Example management CLI commands
This example configuration can be achieved by using the following management CLI commands.
Add the Oracle JDBC driver as a core module.
module add --name=com.oracle --resources=/path/to/ojdbc7.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.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 Oracle JDBC driver.
/subsystem=datasources/jdbc-driver=oracle:add(driver-name=oracle,driver-module-name=com.oracle,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource)
Add the Oracle datasource.
data-source add --name=OracleDS --jndi-name=java:jboss/OracleDS --driver-name=oracle --connection-url=jdbc:oracle:thin:@localhost:1521:XE --user-name=admin --password=admin --validate-on-match=true --background-validation=false --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
11.15.6. Example Oracle XA datasource
The following settings must be applied for the user accessing an Oracle XA datasource in order for XA recovery to operate correctly. The value user
is the user defined to connect from JBoss EAP to Oracle:
-
GRANT SELECT ON sys.dba_pending_transactions TO user;
-
GRANT SELECT ON sys.pending_trans$ TO user;
-
GRANT SELECT ON sys.dba_2pc_pending TO user;
-
GRANT EXECUTE ON sys.dbms_xa TO user;
This is an example of an Oracle XA datasource configuration with XA datasource properties, basic security, and validation options.
Example: Oracle XA datasource configuration
<datasources> <xa-datasource jndi-name="java:jboss/OracleXADS" pool-name="OracleXADS"> <xa-datasource-property name="URL"> jdbc:oracle:thin:@oracleHostName:1521:orcl </xa-datasource-property> <driver>oracle</driver> <xa-pool> <is-same-rm-override>false</is-same-rm-override> </xa-pool> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/> </validation> </xa-datasource> <drivers> <driver name="oracle" module="com.oracle"> <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: Oracle JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.oracle"> <resources> <resource-root path="ojdbc7.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
Example management CLI commands
This example configuration can be achieved by using the following management CLI commands.
Add the Oracle JDBC driver as a core module.
module add --name=com.oracle --resources=/path/to/ojdbc7.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.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 Oracle JDBC driver.
/subsystem=datasources/jdbc-driver=oracle:add(driver-name=oracle,driver-module-name=com.oracle,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource)
Add the Oracle XA datasource.
xa-data-source add --name=OracleXADS --jndi-name=java:jboss/OracleXADS --driver-name=oracle --user-name=admin --password=admin --validate-on-match=true --background-validation=false --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 --same-rm-override=false --xa-datasource-properties={"URL"=>"jdbc:oracle:thin:@oracleHostName:1521:orcl"}
11.15.7. Example Oracle RAC datasource
This is an example of a Real Application Cluster (RAC) datasource configuration with connection information, basic security, and validation options.
Example: Oracle RAC datasource configuration
<datasources> <datasource jndi-name="java:jboss/OracleDS" pool-name="OracleDS"> <connection-url>jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=host2)(PORT=1521))</connection-url> <driver>oracle</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/> </validation> </datasource> <drivers> <driver name="oracle" module="com.oracle"> <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: Oracle JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.oracle"> <resources> <resource-root path="ojdbc7.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
Example management CLI commands
To achieve this example configuration, use the following management CLI commands:
Add the Oracle JDBC driver as a core module:
module add --name=com.oracle --resources=/path/to/ojdbc7.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
Register the Oracle JDBC driver:
/subsystem=datasources/jdbc-driver=oracle:add(driver-name=oracle,driver-module-name=com.oracle,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource)
Add the Oracle RAC datasource:
data-source add --name=OracleDS --jndi-name=java:jboss/OracleDS --driver-name=oracle --connection-url="jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=host2)(PORT=1521))" --user-name=admin --password=admin --validate-on-match=true --background-validation=false --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
Additional resources
11.15.8. Example Oracle RAC XA datasource
This is an example of a RAC datasource configuration with XA datasource properties, basic security, and validation options.
Example: Oracle RAC XA datasource configuration
<datasources> <xa-datasource jndi-name="java:jboss/OracleXADS" pool-name="OracleXADS"> <xa-datasource-property name="URL"> jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=host2)(PORT=1521)) </xa-datasource-property> <driver>oracle</driver> <xa-pool> <is-same-rm-override>false</is-same-rm-override> </xa-pool> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/> </validation> </xa-datasource> <drivers> <driver name="oracle" module="com.oracle"> <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: Oracle JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.oracle"> <resources> <resource-root path="ojdbc7.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
Example management CLI commands
To achieve this example configuration, use the following management CLI commands:
Add the Oracle JDBC driver as a core module:
module add --name=com.oracle --resources=/path/to/ojdbc7.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
Register the Oracle JDBC driver:
/subsystem=datasources/jdbc-driver=oracle:add(driver-name=oracle,driver-module-name=com.oracle,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource)
Add the Oracle RAC XA datasource:
xa-data-source add --name=OracleXADS --jndi-name=java:jboss/OracleXADS --driver-name=oracle --user-name=admin --password=admin --validate-on-match=true --background-validation=false --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 --same-rm-override=false --xa-datasource-properties={"URL"=>"jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=host2)(PORT=1521))"}
11.15.9. Example Microsoft SQL server datasource
This is an example of a Microsoft SQL Server datasource configuration with connection information, basic security, and validation options.
Example: Microsoft SQL server datasource configuration
<datasources> <datasource jndi-name="java:jboss/MSSQLDS" pool-name="MSSQLDS"> <connection-url>jdbc:sqlserver://localhost:1433;DatabaseName=MyDatabase</connection-url> <driver>sqlserver</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter"/> </validation> </datasource> <drivers> <driver name="sqlserver" module="com.microsoft"> <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: Microsoft SQL server JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.microsoft"> <resources> <resource-root path="sqljdbc42.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.transaction.api"/> <module name="jakarta.xml.bind.api"/> </dependencies> </module>
Example management CLI commands
This example configuration can be achieved by using the following management CLI commands.
Add the Microsoft SQL Server JDBC driver as a core module.
module add --name=com.microsoft --resources=/path/to/sqljdbc42.jar --dependencies=java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api,jakarta.xml.bind.api,wildflyee.api,java.se
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 Microsoft SQL Server JDBC driver.
/subsystem=datasources/jdbc-driver=sqlserver:add(driver-name=sqlserver,driver-module-name=com.microsoft,driver-xa-datasource-class-name=com.microsoft.sqlserver.jdbc.SQLServerXADataSource)
Add the Microsoft SQL Server datasource.
data-source add --name=MSSQLDS --jndi-name=java:jboss/MSSQLDS --driver-name=sqlserver --connection-url=jdbc:sqlserver://localhost:1433;DatabaseName=MyDatabase --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter
11.15.10. Example Microsoft SQL server XA datasource
This is an example of a Microsoft SQL Server XA datasource configuration with XA datasource properties, basic security, and validation options.
Example: Microsoft SQL server XA datasource configuration
<datasources> <xa-datasource jndi-name="java:jboss/MSSQLXADS" pool-name="MSSQLXADS"> <xa-datasource-property name="ServerName"> localhost </xa-datasource-property> <xa-datasource-property name="DatabaseName"> mssqldb </xa-datasource-property> <xa-datasource-property name="SelectMethod"> cursor </xa-datasource-property> <driver>sqlserver</driver> <xa-pool> <is-same-rm-override>false</is-same-rm-override> </xa-pool> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter"/> </validation> </xa-datasource> <drivers> <driver name="sqlserver" module="com.microsoft"> <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: Microsoft SQL Server JDBC Driver module.xml
File
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.microsoft"> <resources> <resource-root path="sqljdbc42.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.transaction.api"/> <module name="jakarta.xml.bind.api"/> </dependencies> </module>
Example Management CLI Commands
This example configuration can be achieved by using the following management CLI commands.
Add the Microsoft SQL Server JDBC driver as a core module.
module add --name=com.microsoft --resources=/path/to/sqljdbc42.jar --dependencies=java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api,jakarta.xml.bind.api,wildflyee.api,java.se
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 Microsoft SQL Server JDBC driver.
/subsystem=datasources/jdbc-driver=sqlserver:add(driver-name=sqlserver,driver-module-name=com.microsoft,driver-xa-datasource-class-name=com.microsoft.sqlserver.jdbc.SQLServerXADataSource)
Add the Microsoft SQL Server XA datasource.
xa-data-source add --name=MSSQLXADS --jndi-name=java:jboss/MSSQLXADS --driver-name=sqlserver --user-name=admin --password=admin --validate-on-match=true --background-validation=false --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter --same-rm-override=false --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"mssqldb","SelectMethod"=>"cursor"}
11.15.11. Example IBM DB2 datasource
This is an example of an IBM DB2 datasource configuration with connection information, basic security, and validation options.
Example: IBM DB2 datasource configuration
<datasources> <datasource jndi-name="java:jboss/DB2DS" pool-name="DB2DS"> <connection-url>jdbc:db2://localhost:50000/ibmdb2db</connection-url> <driver>ibmdb2</driver> <pool> <min-pool-size>0</min-pool-size> <max-pool-size>50</max-pool-size> </pool> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter"/> </validation> </datasource> <drivers> <driver name="ibmdb2" module="com.ibm"> <xa-datasource-class>com.ibm.db2.jcc.DB2XADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: IBM DB2 JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.ibm"> <resources> <resource-root path="db2jcc4.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
Example management CLI commands
This example configuration can be achieved by using the following management CLI commands.
Add the IBM DB2 JDBC driver as a core module.
module add --name=com.ibm --resources=/path/to/db2jcc4.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.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 IBM DB2 JDBC driver.
/subsystem=datasources/jdbc-driver=ibmdb2:add(driver-name=ibmdb2,driver-module-name=com.ibm,driver-xa-datasource-class-name=com.ibm.db2.jcc.DB2XADataSource)
Add the IBM DB2 datasource.
data-source add --name=DB2DS --jndi-name=java:jboss/DB2DS --driver-name=ibmdb2 --connection-url=jdbc:db2://localhost:50000/ibmdb2db --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter --min-pool-size=0 --max-pool-size=50
11.15.12. Example IBM DB2 XA datasource
This is an example of an IBM DB2 XA datasource configuration with XA datasource properties, basic security, and validation options.
Example: IBM DB2 XA datasource configuration
<datasources> <xa-datasource jndi-name="java:jboss/DB2XADS" pool-name="DB2XADS"> <xa-datasource-property name="ServerName"> localhost </xa-datasource-property> <xa-datasource-property name="DatabaseName"> ibmdb2db </xa-datasource-property> <xa-datasource-property name="PortNumber"> 50000 </xa-datasource-property> <xa-datasource-property name="DriverType"> 4 </xa-datasource-property> <driver>ibmdb2</driver> <xa-pool> <is-same-rm-override>false</is-same-rm-override> </xa-pool> <security> <user-name>admin</user-name> <password>admin</password> </security> <recovery> <recover-plugin class-name="org.jboss.jca.core.recovery.ConfigurableRecoveryPlugin"> <config-property name="EnableIsValid"> false </config-property> <config-property name="IsValidOverride"> false </config-property> <config-property name="EnableClose"> false </config-property> </recover-plugin> </recovery> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter"/> </validation> </xa-datasource> <drivers> <driver name="ibmdb2" module="com.ibm"> <xa-datasource-class>com.ibm.db2.jcc.DB2XADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: IBM DB2 JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.ibm"> <resources> <resource-root path="db2jcc4.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
Example management CLI commands
This example configuration can be achieved by using the following management CLI commands.
Add the IBM DB2 JDBC driver as a core module.
module add --name=com.ibm --resources=/path/to/db2jcc4.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.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 IBM DB2 JDBC driver.
/subsystem=datasources/jdbc-driver=ibmdb2:add(driver-name=ibmdb2,driver-module-name=com.ibm,driver-xa-datasource-class-name=com.ibm.db2.jcc.DB2XADataSource)
Add the IBM DB2 XA datasource.
xa-data-source add --name=DB2XADS --jndi-name=java:jboss/DB2XADS --driver-name=ibmdb2 --user-name=admin --password=admin --validate-on-match=true --background-validation=false --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter --same-rm-override=false --recovery-plugin-class-name=org.jboss.jca.core.recovery.ConfigurableRecoveryPlugin --recovery-plugin-properties={"EnableIsValid"=>"false","IsValidOverride"=>"false","EnableClose"=>"false"} --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"ibmdb2db","PortNumber"=>"50000","DriverType"=>"4"}
11.15.13. Example Sybase datasource
This is an example of a Sybase datasource configuration with connection information, basic security, and validation options.
Example: Sybase datasource configuration
<datasources> <datasource jndi-name="java:jboss/SybaseDB" pool-name="SybaseDB"> <connection-url>jdbc:sybase:Tds:localhost:5000/DATABASE?JCONNECT_VERSION=6</connection-url> <driver>sybase</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter"/> </validation> </datasource> <drivers> <driver name="sybase" module="com.sybase"> <xa-datasource-class>com.sybase.jdbc4.jdbc.SybXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: Sybase JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.sybase"> <resources> <resource-root path="jconn4.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
Example management CLI commands
This example configuration can be achieved by using the following management CLI commands.
Add the Sybase JDBC driver as a core module.
module add --name=com.sybase --resources=/path/to/jconn4.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.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 Sybase JDBC driver.
/subsystem=datasources/jdbc-driver=sybase:add(driver-name=sybase,driver-module-name=com.sybase,driver-xa-datasource-class-name=com.sybase.jdbc4.jdbc.SybXADataSource)
Add the Sybase datasource.
data-source add --name=SybaseDB --jndi-name=java:jboss/SybaseDB --driver-name=sybase --connection-url=jdbc:sybase:Tds:localhost:5000/DATABASE?JCONNECT_VERSION=6 --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter
11.15.14. Example Sybase XA datasource
This is an example of a Sybase XA datasource configuration with XA datasource properties, basic security, and validation options.
Example: Sybase XA datasource configuration
<datasources> <xa-datasource jndi-name="java:jboss/SybaseXADS" pool-name="SybaseXADS"> <xa-datasource-property name="ServerName"> localhost </xa-datasource-property> <xa-datasource-property name="DatabaseName"> mydatabase </xa-datasource-property> <xa-datasource-property name="PortNumber"> 4100 </xa-datasource-property> <xa-datasource-property name="NetworkProtocol"> Tds </xa-datasource-property> <driver>sybase</driver> <xa-pool> <is-same-rm-override>false</is-same-rm-override> </xa-pool> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter"/> </validation> </xa-datasource> <drivers> <driver name="sybase" module="com.sybase"> <xa-datasource-class>com.sybase.jdbc4.jdbc.SybXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: Sybase JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="com.sybase"> <resources> <resource-root path="jconn4.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
Example management CLI commands
This example configuration can be achieved by using the following management CLI commands.
Add the Sybase JDBC driver as a core module.
module add --name=com.sybase --resources=/path/to/jconn4.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.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 Sybase JDBC driver.
/subsystem=datasources/jdbc-driver=sybase:add(driver-name=sybase,driver-module-name=com.sybase,driver-xa-datasource-class-name=com.sybase.jdbc4.jdbc.SybXADataSource)
Add the Sybase XA datasource.
xa-data-source add --name=SybaseXADS --jndi-name=java:jboss/SybaseXADS --driver-name=sybase --user-name=admin --password=admin --validate-on-match=true --background-validation=false --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter --same-rm-override=false --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"mydatabase","PortNumber"=>"4100","NetworkProtocol"=>"Tds"}
11.15.15. Example MariaDB datasource
This is an example of a MariaDB datasource configuration with connection information, basic security, and validation options.
Example: MariaDB datasource configuration
<datasources> <datasource jndi-name="java:jboss/MariaDBDS" pool-name="MariaDBDS"> <connection-url>jdbc:mariadb://localhost:3306/jbossdb</connection-url> <driver>mariadb</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/> </validation> </datasource> <drivers> <driver name="mariadb" module="org.mariadb"> <driver-class>org.mariadb.jdbc.Driver</driver-class> <xa-datasource-class>org.mariadb.jdbc.MySQLDataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: MariaDB JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="org.mariadb"> <resources> <resource-root path="mariadb-java-client-3.3.0.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="org.slf4j"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
Example management CLI commands
This example configuration can be achieved by using the following management CLI commands.
Add the MariaDB JDBC driver as a core module.
module add --name=org.mariadb --resources=/path/to/mariadb-java-client-3.3.0.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api,org.slf4j
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 MariaDB JDBC driver.
/subsystem=datasources/jdbc-driver=mariadb:add(driver-name=mariadb,driver-module-name=org.mariadb,driver-xa-datasource-class-name=org.mariadb.jdbc.MySQLDataSource, driver-class-name=org.mariadb.jdbc.Driver)
Add the MariaDB datasource.
data-source add --name=MariaDBDS --jndi-name=java:jboss/MariaDBDS --driver-name=mariadb --connection-url=jdbc:mariadb://localhost:3306/jbossdb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
11.15.16. Example MariaDB XA datasource
This is an example of a MariaDB XA datasource configuration with XA datasource properties, basic security, and validation options.
Example: MariaDB XA datasource configuration
<datasources> <xa-datasource jndi-name="java:jboss/MariaDBXADS" pool-name="MariaDBXADS"> <xa-datasource-property name="ServerName"> localhost </xa-datasource-property> <xa-datasource-property name="DatabaseName"> mariadbdb </xa-datasource-property> <driver>mariadb</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/> </validation> </xa-datasource> <drivers> <driver name="mariadb" module="org.mariadb"> <driver-class>org.mariadb.jdbc.Driver</driver-class> <xa-datasource-class>org.mariadb.jdbc.MySQLDataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: MariaDB JDBC driver module.xml
file
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.9" name="org.mariadb"> <resources> <resource-root path="mariadb-java-client-3.3.0.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="org.slf4j"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
Example management CLI commands
This example configuration can be achieved by using the following management CLI commands.
Add the MariaDB JDBC driver as a core module.
module add --name=org.mariadb --resources=/path/to/mariadb-java-client-3.3.0.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api,org.slf4j
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 MariaDB JDBC driver.
/subsystem=datasources/jdbc-driver=mariadb:add(driver-name=mariadb,driver-module-name=org.mariadb,driver-xa-datasource-class-name=org.mariadb.jdbc.MySQLDataSource, driver-class-name=org.mariadb.jdbc.Driver)
Add the MariaDB XA datasource.
xa-data-source add --name=MariaDBXADS --jndi-name=java:jboss/MariaDBXADS --driver-name=mariadb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"mariadbdb"}
11.15.17. Example MariaDB Galera Cluster datasource
This is an example of a MariaDB Galera Cluster datasource configuration with connection information, basic security, and validation options.
MariaDB Galera Cluster does not support XA transactions.
Example: MariaDB Galera Cluster datasource configuration
<datasources> <datasource jndi-name="java:jboss/MariaDBGaleraClusterDS" pool-name="MariaDBGaleraClusterDS"> <connection-url>jdbc:mariadb://192.168.1.1:3306,192.168.1.2:3306/jbossdb</connection-url> <driver>mariadb</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/> <validate-on-match>true</validate-on-match> <background-validation>false</background-validation> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/> </validation> </datasource> <drivers> <driver name="mariadb" module="org.mariadb"> <driver-class>org.mariadb.jdbc.Driver</driver-class> <xa-datasource-class>org.mariadb.jdbc.MySQLDataSource</xa-datasource-class> </driver> </drivers> </datasources>
Example: MariaDB JDBC driver module.xml
file
<?xml version='1.0' encoding='UTF-8'?> <module xmlns="urn:jboss:module:1.9" name="org.mariadb"> <resources> <resource-root path="mariadb-java-client-3.3.0.jar"/> </resources> <dependencies> <module name="wildflyee.api"/> <module name="java.se"/> <module name="java.xml" export="true"/> <module name="java.xml.crypto" export="true"/> <module name="jdk.xml.dom" export="true"/> <module name="org.slf4j"/> <module name="jakarta.transaction.api"/> </dependencies> </module>
Example management CLI commands
This example configuration can be achieved by using the following management CLI commands.
Add the MariaDB JDBC driver as a core module.
module add --name=org.mariadb --resources=/path/to/mariadb-java-client-3.3.0.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api,org.slf4j
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 MariaDB JDBC driver.
/subsystem=datasources/jdbc-driver=mariadb:add(driver-name=mariadb,driver-module-name=org.mariadb,driver-xa-datasource-class-name=org.mariadb.jdbc.MySQLDataSource, driver-class-name=org.mariadb.jdbc.Driver)
Add the MariaDB Galera Cluster datasource.
data-source add --name=MariaDBGaleraClusterDS --jndi-name=java:jboss/MariaDBGaleraClusterDS --driver-name=mariadb --connection-url=jdbc:mariadb://192.168.1.1:3306,192.168.1.2:3306/jbossdb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter