Concurrent, fast, and fully-featured JDBC connection pool, which offers advanced performance monitoring and metrics generation capabilities. Vibur can detect and log slow SQL query execution and extra-large ResultSet retrieval. It also provides JDBC statement caching and Hibernate integration, among other features.

The pool initial size; i.e., the initial number of connections allocated in this JDBC pool.

The pool max size; i.e., the maximum number of connections that can be allocated in this JDBC pool.

If true, guarantees that the threads invoking the pool's take methods will be selected to obtain a connection from it in FIFO order, and no thread will be starved out from accessing the JDBC pool connections.

If true, the JDBC connections pool will keep information for the current stack trace of every taken from it connection.

The DataSource/pool name, mostly useful for JMX identification and Vibur logs analysis. This name must be unique among all names for all configured Vibur pools. The default name is "p" + an auto-generated integer ID. If the configured name is not unique, the default name will be used instead.

The preferred way to configure/inject the JDBC Driver through which the Connections will be generated.

Vibur will try to determine which is the JDBC Driver to be used in this particular order: if the driver property is specified it will be the one that will be used; if this property is not specified then Vibur will check the driverClassName property and if it is specified the JDBC Driver instance will be created from it; if this property is also not specified then Vibur will retrieve the JDBC driver based on the configured jdbcUrl.

The driver properties that will be used in the call to Driver.connect().

The database driver class name. This is an optional parameter if the driver is JDBC 4 compliant. If specified, a call to Class.forName(driverClassName).newInstance() will be issued during the Vibur DBCP initialization. This is needed when Vibur DBCP is used in an OSGi container and may also be helpful if Vibur DBCP is used in an Apache Tomcat web application that has its JDBC driver JAR file packaged in the app WEB-INF/lib directory. If this property is not specified, Vibur DBCP will fallback to the standard JavaSE Service Provider mechanism in order to find the driver.

The database JDBC connection string.

The user name to use when connecting to the database.

The password to use when connecting to the database.

If specified, this externalDataSource will be used as an alternative way to obtain the raw connections for the pool instead of calling DriverManager.getConnection().

In rare circumstances, the application may need to obtain a non-pooled connection from the pool after the pool has been terminated. This may happen as part of some post-caching or application shutdown execution path.

Controls whether the pool's DataSource and the created from it JDBC objects (Connection, Statement, etc) support unwrapping/exposing of the underlying (proxied) JDBC objects. If disabled, the call to Wrapper.isWrapperFor() on any of these objects will always return false.

Time to wait before a call to DataSource.getConnection() times out and throws an SQLTimeoutException. More precisely, that is the time to wait to obtain a connection from the pool when there is a ready and valid connection in the pool. 0 means forever.

If there is no ready and valid connection in the pool, and if the maximum pool capacity is not reached yet, the total time that the call to getConnection() can take may include the time to lazily create a new connection, and is defined as:

maxTimeoutInMs = connectionTimeoutInMs + loginTimeoutInSeconds * 1000

Login timeout, which will be passed to the DriverManager.setLoginTimeout() or getExternalDataSource().setLoginTimeout() method during the initialization process of the DataSource.

After attempting to lazily create a JDBC Connection as part of the DataSource.getConnection() flow and failing with an SQLException, wait for this long before attempting again.

After attempting to lazily create a JDBC Connection as part of the DataSource.getConnection() flow and failing with an SQLException, retry maximum these many times before giving up.

If the connection has stayed in the JDBC pool for at least connectionIdleLimitInSeconds, it will be validated using the testConnectionQuery before being given to the application. If set to 0, it will always validate the connection taken from the pool. If set to a negative number, it will never validate the connection taken from the pool.

Applications which have strict requirements and expectations that the JDBC Connection checked out from the pool is valid at the time of the check out may benefit from reducing the value of connectionIdleLimitInSeconds to 1 second. Setting the value to 0 should be done with care as each connection validation requires one additional return-trip to the database.

Also see the introductory paragraph from the connection timeouts and retries settings section.

The timeout that will be passed to the call to testConnectionQuery when a taken from the pool JDBC Connection is validated before use, or when initSQL is executed (if specified). 0 means no limit.

Used to test the validity of a JDBC Connection. If the connectionIdleLimitInSeconds is set to a non-negative number, the testConnectionQuery should be set to a valid SQL query; for example, SELECT 1, or isValid, in which case the Connection.isValid() method will be used.

Similar to the spec for Connection.isValid(int), if a custom testConnectionQuery is specified, it will be executed in the context of the current transaction.

Note that if the driver is JDBC 4 compliant, using the default isValid value is strongly recommended, as the driver can often use some ad-hoc and very efficient mechanism via which to positively verify whether the given JDBC connection is still valid or not.

An SQL query that will be run only once when a JDBC Connection is first created. This property should be set to a valid SQL query, to a null value that means no query, or to isValid, which means the Connection.isValid() method will be used. A case in which this property can be useful is when the application is connecting to the database via some middleware; for example, connecting to PostgreSQL server(s) via PgBouncer.

This option applies only if testConnectionQuery or initSQL are enabled and if at least one of them has a value different than isValid. If enabled, the calls to the validation or initialization SQL query will be preceded by a call to setNetworkTimeout(), and after that the original network timeout value will be restored.

Note that it is responsibility of the application to make sure that the used JDBC driver supports the setNetworkTimeout() method. Also, a suitable networkTimeoutExecutor needs to be configured, see the next configuration option.

Also see the introductory paragraph from the connection timeouts and retries settings section.

This option applies only if useNetworkTimeout is enabled. This is the Executor that will be passed to the call of setNetworkTimeout().

Note that it is responsibility of the application to supply Executor that is suitable for the needs of the concrete JDBC driver. For example, some JDBC drivers may require a synchronous Executor.

The underlying SQL queries (including their concrete parameters) from a JDBC Statement execute... calls taking longer than or equal to this time limit are logged at the WARN level. A value of 0 will log all such calls. A negative number disables it.

Note that while a JDBC Statement execute... call duration is roughly equivalent to the execution time of the underlying SQL query, the overall call duration may also include some Java GC time, JDBC driver specific execution time, and context switching time (the last could be significant if the application has a large thread count).

Will apply only if logQueryExecutionLongerThanMs is enabled, and if set to true, will log at the WARN level the current JDBC Statement execute... call stack trace.

A log sample generated by Vibur DBCP for slow SQL queries is shown here.

The underlying SQL queries (including their concrete parameters) from a JDBC Statement execute... calls that generate ResultSets with length greater than or equal to this limit are logged at WARN level. A negative number disables it. Retrieving of a large ResultSet may have negative effect on the application performance and may sometimes be an indication of a very subtle application bug, where the whole ResultSet is retrieved, but only the first few records of it are subsequently read and processed.

The logging is done at the moment when the application issues a call to the ResultSet.close() method. Applications that rely on the implicit closure of the ResultSet when the generated it Statement is closed, will not be able to benefit from this logging functionality.

The calculation of the ResultSet size is done based on the number of calls that the application has issued to the ResultSet.next() method. In most of the cases this is a very accurate and non-intrusive method to calculate the ResultSet size, particularly in the case of a Hibernate or Spring Framework JDBC application. However, this calculation mechanism may give inaccurate results in some advanced cases where the application navigates through the ResultSet with methods such as first(), last(), or afterLast().

Will apply only if logLargeResultSet is enabled, and if set to true, will log at WARN level the current ResultSet.close() call stack trace.

Enables or disables the collection of concrete SQL query parameters for StatementExecution hook and ResultSetRetrieval hook. Also see logQueryExecutionLongerThanMs and logLargeResultSet. Disabling parameters collection can be useful if there are specific compliance requirements for the user application.

The DataSource.getConnection() method calls that take longer than or equal to this time limit are logged at the WARN level. A value of 0 will log all such calls. A negative number disables it.

If the value of logConnectionLongerThanMs is greater than connectionTimeoutInMs, then logConnectionLongerThanMs will be set to the value of connectionTimeoutInMs.

Will apply only if logConnectionLongerThanMs is enabled, and if set to true, will log at the WARN level the current getConnection() call stack trace.

A log sample generated by Vibur DBCP for slow getConnection() calls is shown here.

If set to true, and if the connectionTimeoutInMs is reached and the call to getConnection() fails with throwing an SQLTimeoutException, will log at WARN level information about all currently taken connections, including the stack traces of the threads that have taken them (at the moment when they have taken them), plus the threads names and states, as well as the current execution stack traces of these threads, if they are still alive.

This options implies that the poolEnableConnectionTracking option is enabled, and if the last is not explicitly enabled it will be implicitly enabled as part of the processing of this option.

Note that this option should be used for troubleshooting purposes only, as it may generate a very large log output. The exact format of the logged message is controlled by the takenConnectionsFormatter.

This option will apply only if logTakenConnectionsOnTimeout is enabled, and if set to true, will add to the log generated by ViburDataSource.getTakenConnectionsStackTraces() the current stack traces of all live threads in the JVM that are not holding connections. In other words, the combination of these two options is equivalent to generating a full JVM thread dump, and thus it has to be used for troubleshooting purposes only, as it may generate a very large log output.

If different than null, this regex will be matched against the string representation of each stack trace line that needs to be logged according logStackTraceForLongConnection, logStackTraceForLargeResultSet, logStackTraceForLongQueryExecution, logTakenConnectionsOnTimeout, and logAllStackTracesOnTimeout. Stack trace lines which string representation matches this regex will be logged while all others will be skipped. This may help to significantly reduce the length of the logged stack traces. A value of null disables the regex matching and (by default) all stack trace lines will be logged.

For example, if the logging is done in the context of a Tomcat application, and if the application wants to omit from logging all stack trace lines that contain doFilter in them, then the application can set the following compiled regex pattern: Pattern.compile("^((?!doFilter).)*$")

The interface implemented by this configuration option allows the application to implement custom formatting to String of the TakenConnection[] array. Note that the default formatter uses the logLineRegex for filtering.

A programming hook that will be invoked only once after the raw JDBC Connection is first created. This is the place to execute an application specific one-off Connection setup logic, such as setting the default Connection network timeout or similar. The hook execution should take as short time as possible.

This hook complements the DestroyConnection hook, which is invoked after the raw JDBC Connection is destroyed.

A programming hook that will be invoked on the raw JDBC Connection after it was taken from the pool as part of the DataSource.getConnection() flow. This is the place to execute an application specific per taken Connection logic, such as setting the default database schema or role, if they are different for the different getConnection() calls. The hook execution should take as short time as possible.

This hook complements the CloseConnection hook, which is invoked before the raw JDBC Connection is restored back to the pool.

A programming hook that will be invoked on the raw JDBC Connection before it is restored back to the pool as part of the Connection.close() flow. This is the place to execute an application specific per taken Connection winding down logic, if needed. The hook execution should take as short time as possible.

This hook complements the GetConnection hook, which is invoked after the raw JDBC Connection is taken from the pool.

A programming hook that will be invoked only once after the raw JDBC Connection is closed/destroyed by the ConnectionFactory. The hook execution should take as short time as possible.

This hook complements the InitConnection hook, which is invoked after the raw JDBC Connection is first created.

A programming hook that will be invoked only when the call to DataSource.getConnection() timeouts. In fact, the invocation of this hook indicates that the current call to getConnection() will throw an SQLTimeoutException. The application can use this hook to format and redirect the generated taken connections log to a different than the usual log location, for example, to Amazon S3. Note that in order to enable the taken connections tracking the application must set poolEnableConnectionTracking to true.

The default hook uses the takenConnectionsFormatter; it can be disabled via setting logTakenConnectionsOnTimeout to false.

Note that if the thread waiting on a getConnection() call is interrupted, this does not count as a timeout. The hook execution should take as short time as possible.

A programming hook that will be invoked before a method on the proxied JDBC interfaces is invoked. It intercepts (almost) all such method calls. Methods inherited from the Object class, methods related to the closed state of the JDBC objects (e.g., close(), isClosed()), as well as methods from the Wrapper interface are not intercepted. The hook execution should take as short time as possible.

A programming hook that will be invoked around the call of each JDBC Statement "execute..." method. The hook is responsible for using the supplied StatementProceedingPoint to pass the call to the intercepted Statement "execute..." method or to the next registered StatementExecution hook. The hook execution should take as short time as possible.

An example implementation for this hook may look like:

(proxy, method, args, sqlQuery, sqlQueryParams, proceed) -> { // Java 8
    try {
        // do something before the real method execution, for example,
        // increment a queriesInProcess counter or start a stopwatch

        Object result = proceed.on(proxy, method, args, sqlQuery,
            sqlQueryParams, proceed);
        return result;

    } finally {
        // do something after the real method execution, for example,
        // decrement a queriesInProcess counter or stop a stopwatch
    }
}             

A programming hook that will be invoked at the end of each ResultSet retrieval as part of the ResultSet.close() flow. For implementation details see the comments for logLargeResultSet. The hook execution should take as short time as possible.

If set to true, will clear the SQL Warnings (if any) from the JDBC Connection after use and before returning it to the pool. Similarly, if statement caching is enabled, will clear the SQL Warnings (if any) from the JDBC Prepared or Callable Statement after use and before returning it to the statement cache.

If set to true, will reset the four connection default values below, always after the connection is restored (returned) to the pool after use. If the calling application never changes these default values, resetting them is not needed.

The default auto-commit state of the created connections.

The default read-only state of the created connections.

The default transaction isolation level for the created connections.

The default database catalog of the created connections.

Defines the maximum statement cache size. 0 disables it, and the max size allowed is 2000. If the statement's cache is not enabled, the client application may safely exclude the dependency on ConcurrentLinkedHashMap.

It is worth noting that the CLHM implementation employs a LRU eviction strategy, and that the eviction of the LRU map entry happens in the context of the thread that has executed an insert (putIfAbsent) map operation - which has increased the CLHM size above its predefined maxSize.

The fully qualified pool reducer class name. This pool reducer class will be instantiated via reflection, and will be instantiated only if reducerTimeIntervalInSeconds is greater than 0. It must implement the ThreadedPoolReducer interface and must also have a public constructor accepting a single argument of type ViburDBCPConfig.

This setting is useful for applications that need to provide their own custom monitoring of the number of currently allocated in the pool connections, including their own logic for reducing the number of currently unused connections.

The time period after which the poolReducer will try to (possibly) reduce the number of created but unused JDBC connections in this pool. 0 disables it.

Note that enabling the poolReducer will cause a background daemon thread to be started for the needs of the configured poolReducerClass. This thread is the only service thread that will be ever started for a configured Vibur DBCP instance.

How many times the poolReducer will wake up during the given reducerTimeIntervalInSeconds period in order to sample various statistics from the pool.

The list of critical SQL states as a comma separated values, see this stackoverflow answer. If an SQL exception that has any of these SQL states is thrown, then all connections in the pool will be considered invalid and will be closed.

Enables or disables the Vibur DBCP DataSource JMX exposure. Also see the pool name configuration option.