14.4. Datasource Configuration

14.4.1. Datasource Parameters

Table 14.2. Datasource parameters common to non-XA and XA datasources
Parameter	Description
jndi-name	The unique JNDI name for the datasource.
pool-name	The name of the management pool for the datasource.
enabled	Whether or not the datasource is enabled.
use-java-context	Whether to bind the datasource to global JNDI.
spy	Enable `spy` functionality on the JDBC layer. This logs all JDBC traffic to the datasource. Note that the logging category `jboss.jdbc.spy` must also be set to the log level `DEBUG` in the logging subsystem.
use-ccm	Enable the cached connection manager.
new-connection-sql	A SQL statement which executes when the connection is added to the connection pool.
transaction-isolation	One of the following: TRANSACTION_READ_UNCOMMITTED TRANSACTION_READ_COMMITTED TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE TRANSACTION_NONE
url-delimiter	The delimiter for URLs in a connection-url for High Availability (HA) clustered databases.
url-selector-strategy-class-name	A class that implements interface `org.jboss.jca.adapters.jdbc.URLSelectorStrategy`.
security	Contains child elements which are security settings. See Table 14.7, “Security parameters”.
validation	Contains child elements which are validation settings. See Table 14.8, “Validation parameters”.
timeout	Contains child elements which are timeout settings. See Table 14.9, “Timeout parameters”.
statement	Contains child elements which are statement settings. See Table 14.10, “Statement parameters”.

Table 14.3. Non-XA datasource parameters
Parameter	Description
jta	Enable JTA integration for non-XA datasources. Does not apply to XA datasources.
connection-url	The JDBC driver connection URL.
driver-class	The fully-qualified name of the JDBC driver class.
connection-property	Arbitrary connection properties passed to the method `Driver.connect(url,props)`. Each connection-property specifies a string name/value pair. The property name comes from the name, and the value comes from the element content.
pool	Contains child elements which are pooling settings. See Table 14.5, “Pool parameters common to non-XA and XA datasources”.

Table 14.4. XA datasource parameters
Parameter	Description
xa-datasource-property	A property to assign to implementation class `XADataSource`. Specified by name=value. If a setter method exists, in the format `setName`, the property is set by calling a setter method in the format of `setName(value)`.
xa-datasource-class	The fully-qualified name of the implementation class `javax.sql.XADataSource`.
driver	A unique reference to the classloader module which contains the JDBC driver. The accepted format is driverName#majorVersion.minorVersion.
xa-pool	Contains child elements which are pooling settings. See Table 14.5, “Pool parameters common to non-XA and XA datasources” and Table 14.6, “XA pool parameters”.
recovery	Contains child elements which are recovery settings. See Table 14.11, “Recovery parameters”.

Table 14.5. Pool parameters common to non-XA and XA datasources
Parameter	Description
min-pool-size	The minimum number of connections a pool holds.
max-pool-size	The maximum number of connections a pool can hold.
prefill	Whether to try to prefill the connection pool. An empty element denotes a `true` value. The default is `false`.
use-strict-min	Whether the pool-size is strict. Defaults to `false`.
flush-strategy	Whether the pool is flushed in the case of an error. Valid values are: FailingConnectionOnly IdleConnections EntirePool The default is `FailingConnectionOnly`.
allow-multiple-users	Specifies if multiple users will access the datasource through the getConnection(user, password) method, and whether the internal pool type accounts for this behavior.

Table 14.6. XA pool parameters
Parameter	Description
is-same-rm-override	Whether the `javax.transaction.xa.XAResource.isSameRM(XAResource)` class returns `true` or `false`.
interleaving	Whether to enable interleaving for XA connection factories.
no-tx-separate-pools	Whether to create separate sub-pools for each context. This is required for Oracle datasources, which do not allow XA connections to be used both inside and outside of a JTA transaction. Using this option will cause your total pool size to be twice `max-pool-size`, because two actual pools will be created.
pad-xid	Whether to pad the Xid.
wrap-xa-resource	Whether to wrap the XAResource in an `org.jboss.tm.XAResourceWrapper` instance.

Table 14.7. Security parameters
Parameter	Description
user-name	The username to use to create a new connection.
password	The password to use to create a new connection.
security-domain	Contains the name of a JAAS security-manager which handles authentication. This name correlates to the application-policy/name attribute of the JAAS login configuration.
reauth-plugin	Defines a reauthentication plug-in to use to reauthenticate physical connections.

Table 14.8. Validation parameters
Parameter	Description
valid-connection-checker	An implementation of interface `org.jboss.jca.adaptors.jdbc.ValidConnectionChecker` which provides a `SQLException.isValidConnection(Connection e)` method to validate a connection. An exception means the connection is destroyed. This overrides the parameter `check-valid-connection-sql` if it is present.
check-valid-connection-sql	An SQL statement to check validity of a pool connection. This may be called when a managed connection is taken from a pool for use.
validate-on-match	Indicates whether connection level validation is performed when a connection factory attempts to match a managed connection for a given set. Specifying "true" for `validate-on-match` is typically not done in conjunction with specifying "true" for `background-validation`. `Validate-on-match` is needed when a client must have a connection validated prior to use. This parameter is false by default.
background-validation	Specifies that connections are validated on a background thread. Background validation is a performance optimization when not used with `validate-on-match`. If `validate-on-match` is true, using `background-validation` could result in redundant checks. Background validation does leave open the opportunity for a bad connection to be given to the client for use (a connection goes bad between the time of the validation scan and prior to being handed to the client), so the client application must account for this possibility.
background-validation-millis	The amount of time, in milliseconds, that background validation runs.
use-fast-fail	If true, fail a connection allocation on the first attempt, if the connection is invalid. Defaults to `false`.
stale-connection-checker	An instance of `org.jboss.jca.adapters.jdbc.StaleConnectionChecker` which provides a Boolean `isStaleConnection(SQLException e)` method. If this method returns `true`, the exception is wrapped in an `org.jboss.jca.adapters.jdbc.StaleConnectionException`, which is a subclass of `SQLException`.
exception-sorter	An instance of `org.jboss.jca.adapters.jdbc.ExceptionSorter` which provides a Boolean `isExceptionFatal(SQLException e)` method. This method validates whether an exception is broadcast to all instances of `javax.resource.spi.ConnectionEventListener` as a `connectionErrorOccurred` message.

Table 14.9. Timeout parameters
Parameter	Description
use-try-lock	Uses `tryLock()` instead of `lock()`. This attempts to obtain the lock for the configured number of seconds, before timing out, rather than failing immediately if the lock is unavailable. Defaults to `60` seconds. As an example, to set a timeout of 5 minutes, set `<use-try-lock>`300`</use-try-lock>`.
blocking-timeout-millis	The maximum time, in milliseconds, to block while waiting for a connection. After this time is exceeded, an exception is thrown. This blocks only while waiting for a permit for a connection, and does not throw an exception if creating a new connection takes a long time. Defaults to 30000, which is 30 seconds.
idle-timeout-minutes	The maximum time, in minutes, before an idle connection is closed. The actual maximum time depends upon the idleRemover scan time, which is half of the smallest `idle-timeout-minutes` of any pool.
set-tx-query-timeout	Whether to set the query timeout based on the time remaining until transaction timeout. Any configured query timeout is used if no transaction exists. Defaults to `false`.
query-timeout	Timeout for queries, in seconds. The default is no timeout.
allocation-retry	The number of times to retry allocating a connection before throwing an exception. The default is `0`, so an exception is thrown upon the first failure.
allocation-retry-wait-millis	How long, in milliseconds, to wait before retrying to allocate a connection. The default is 5000, which is 5 seconds.
xa-resource-timeout	If non-zero, this value is passed to method `XAResource.setTransactionTimeout`.

Table 14.10. Statement parameters
Parameter	Description
track-statements	Whether to check for unclosed statements when a connection is returned to a pool and a statement is returned to the prepared statement cache. If false, statements are not tracked. `true`: statements and result sets are tracked, and a warning is issued if they are not closed. `false`: neither statements or result sets are tracked. `nowarn`: statements are tracked but no warning is issued. This is the default.
prepared-statement-cache-size	The number of prepared statements per connection, in a Least Recently Used (LRU) cache.
share-prepared-statements	Whether asking for the same statement twice without closing it uses the same underlying prepared statement. The default is `false`.

Table 14.11. Recovery parameters
Parameter	Description
recover-credential	A username/password pair or security domain to use for recovery.
recover-plugin	An implementation of the `org.jboss.jca.core.spi.recoveryRecoveryPlugin` class, to be used for recovery.

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.