6.7. Datasource Configuration
6.7.1. Datasource Parameters
| 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:
|
| 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 6.8, “Security parameters”.
|
| validation |
Contains child elements which are validation settings. See Table 6.9, “Validation parameters”.
|
| timeout |
Contains child elements which are timeout settings. See Table 6.10, “Timeout parameters”.
|
| statement |
Contains child elements which are statement settings. See Table 6.11, “Statement 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 6.6, “Pool parameters common to non-XA and XA datasources”.
|
| url-delimiter |
The delimiter for URLs in a connection-url for High Availability (HA) clustered databases.
|
| 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 class loader module which contains the JDBC driver. The accepted format is driverName#majorVersion.minorVersion.
|
| xa-pool |
Contains child elements which are pooling settings. See Table 6.6, “Pool parameters common to non-XA and XA datasources” and Table 6.7, “XA pool parameters”.
|
| recovery |
Contains child elements which are recovery settings. See Table 6.12, “Recovery parameters”.
|
| 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. The default is false. |
| use-strict-min | Whether the idle connection scan should strictly stop marking for closure of any further connections, once the min-pool-size has been reached. The default value is false. |
| flush-strategy |
Whether the pool is flushed in the case of an error. Valid values are:
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. |
| 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.
|
| 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. |
| 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.
|
| 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. If not specified, the default is
30 minutes. 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.
|
| 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.
|
| prepared-statement-cache-size | The number of prepared statements per connection, in a Least Recently Used (LRU) cache. |
| share-prepared-statements |
Whether JBoss EAP should cache, instead of close or terminate, the underlying physical statement when the wrapper supplied to the application is closed by application code. The default is
false.
|
| 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.
|
6.7.2. Datasource Connection URLs
| Datasource | Connection URL |
|---|---|
| PostgreSQL | jdbc:postgresql://SERVER_NAME:PORT/DATABASE_NAME |
| MySQL | jdbc:mysql://SERVER_NAME:PORT/DATABASE_NAME |
| Oracle | jdbc:oracle:thin:@ORACLE_HOST:PORT:ORACLE_SID |
| IBM DB2 | jdbc:db2://SERVER_NAME:PORT/DATABASE_NAME |
| Microsoft SQLServer | jdbc:sqlserver://SERVER_NAME:PORT;DatabaseName=DATABASE_NAME Note
The jdbc:microsoft:sqlserver://SERVER_NAME:PORT;DatabaseName=DATABASE_NAME template does not work with new database.
|
6.7.3. Datasource Extensions
Datasource deployments can use several extensions in the JDBC resource adapter to improve the connection validation, and check whether an exception should reestablish the connection. Those extensions are:
| Datasource Extension | Configuration Parameter | Description |
|---|---|---|
| org.jboss.jca.adapters.jdbc.spi.ExceptionSorter | <exception-sorter> | Checks whether an SQLException is fatal for the connection on which it was thrown |
| org.jboss.jca.adapters.jdbc.spi.StaleConnectionChecker | <stale-connection-checker> | Wraps stale SQLExceptions in a org.jboss.jca.adapters.jdbc.StaleConnectionException |
| org.jboss.jca.adapters.jdbc.spi.ValidConnection | <valid-connection-checker> | Checks whether a connection is valid for use by the application |
JBoss EAP 6 also features implementations of these extensions for several supported databases.
Extension Implementations
- Generic
- org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.novendor.NullStaleConnectionChecker
- org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker
- org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker
- PostgreSQL
- org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
- MySQL
- org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
- org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker
- IBM DB2
- org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker
- org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker
- Sybase
- org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker
- Microsoft SQLServer
- org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker
- Oracle
- org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker
- org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker
6.7.4. View Datasource Statistics
You can view statistics from defined datasources for both the
jdbc and pool using appropriately modified versions of the commands below:
Example 6.15. CLI for domain mode:
Change
/host=master/server=server-one and data-source=ExampleDS according to the environment.
[domain@localhost:9999 /] /host=master/server=server-one/subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true)
{
"outcome" => "success",
"result" => {
"ActiveCount" => "0",
"AvailableCount" => "20",
"AverageBlockingTime" => "0",
"AverageCreationTime" => "0",
"CreatedCount" => "0",
"DestroyedCount" => "0",
"MaxCreationTime" => "0",
"MaxUsedCount" => "0",
"MaxWaitTime" => "0",
"TimedOut" => "0",
"TotalBlockingTime" => "0",
"TotalCreationTime" => "0"
}
}
Example 6.16. CLI for standalone mode:
Change
data-source=ExampleDS according to the environment.
[standalone@localhost:9999 /] /subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true)
{
"outcome" => "success",
"result" => {
"ActiveCount" => "0",
"AvailableCount" => "20",
"AverageBlockingTime" => "0",
"AverageCreationTime" => "0",
"CreatedCount" => "0",
"DestroyedCount" => "0",
"MaxCreationTime" => "0",
"MaxUsedCount" => "0",
"MaxWaitTime" => "0",
"TimedOut" => "0",
"TotalBlockingTime" => "0",
"TotalCreationTime" => "0"
}
}
Note
Ensure you specify the
include-runtime=true argument, as all statistics are runtime only information and the default is false.
6.7.5. Datasource Statistics
Core Statistics
The following table contains a list of the supported datasource core statistics:
| Name | Description |
|---|---|
ActiveCount |
The number of active connections. Each of the connections is either in use by an application or available in the pool
|
AvailableCount |
The number of available connections in the pool.
|
AverageBlockingTime |
The average time spent blocking on obtaining an exclusive lock on the pool. The value is in milliseconds.
|
AverageCreationTime |
The average time spent creating a connection. The value is in milliseconds.
|
CreatedCount |
The number of connections created.
|
DestroyedCount |
The number of connections destroyed.
|
InUseCount |
The number of connections currently in use.
|
MaxCreationTime |
The maximum time it took to create a connection. The value is in milliseconds.
|
MaxUsedCount |
The maximum number of connections used.
|
MaxWaitCount |
The maximum number of requests waiting for a connection at the same time.
|
MaxWaitTime |
The maximum time spent waiting for an exclusive lock on the pool.
|
TimedOut |
The number of timed out connections.
|
TotalBlockingTime |
The total time spent waiting for an exclusive lock on the pool. The value is in milliseconds.
|
TotalCreationTime |
The total time spent creating connections. The value is in milliseconds.
|
JDBC Statistics
The following table contains a list of the supported datasource JDBC statistics:
| Name | Description |
|---|---|
PreparedStatementCacheAccessCount |
The number of times that the statement cache was accessed.
|
PreparedStatementCacheAddCount |
The number of statements added to the statement cache.
|
PreparedStatementCacheCurrentSize |
The number of prepared and callable statements currently cached in the statement cache.
|
PreparedStatementCacheDeleteCount |
The number of statements discarded from the cache.
|
PreparedStatementCacheHitCount |
The number of times that statements from the cache were used.
|
PreparedStatementCacheMissCount |
The number of times that a statement request could not be satisfied with a statement from the cache.
|
You can enable
Core and JDBC statistics using appropriately modified versions of the following commands:
/subsystem=datasources/data-source=ExampleDS/statistics=pool:write-attribute(name=statistics-enabled,value=true)
/subsystem=datasources/data-source=ExampleDS/statistics=jdbc:write-attribute(name=statistics-enabled,value=true)
