Understanding Tomcat JDBC Connection Pool Configuration and Validation Parameters

During a large‑scale network change, some applications experienced database connections that did not automatically recover after the network was restored, requiring a restart. This is often caused by improper configuration of the database connection pool, so we use Tomcat‑JDBC as an example to examine important pool settings.

Database connections are heavyweight resources, so they are typically pooled: a set of pre‑created connections is kept ready, and applications borrow and return them instead of creating new ones each time.

Because a pooled connection is essentially a TCP socket, its validity can become uncertain if it is idle for a while. When an application borrows a connection that has become invalid, an exception occurs, highlighting the need for connection‑validation mechanisms.

Tomcat‑JDBC (and most other pools) provides several validation options:

testOnBorrow : validates a connection when it is borrowed. The actual test occurs only if the time since the last validation exceeds validationInterval , and the SQL used is defined by validationQuery (commonly SELECT 1 ).

testOnReturn : validates a connection when it is returned to the pool, also respecting validationInterval .

testWhileIdle : a background thread periodically scans idle connections and validates them when the interval has elapsed.

testOnConnect : validates a connection at creation time, bypassing validationInterval . If initSQL is set, it is used for the test instead of validationQuery .

Other important pool parameters include:

maxActive, maxIdle, minIdle, initialSize : control the maximum number of active connections, idle limits, and the number of connections created at startup.

maxAge : forces a connection to be closed when its age exceeds the configured value, helping to avoid long‑lived resource leaks.

removeAbandoned, logAbandoned, abandonWhenPercentageFull, removeAbandonedTimeout : detect and close connections that have been checked out for longer than a threshold, optionally logging stack traces for debugging.

Performance testing was conducted on MySQL 5.6 with three client machines, each running multiple threads that continuously executed SELECT 1 . Results showed that enabling testOnBorrow adds only a negligible latency (≈0.0001 s) while greatly improving reliability during network glitches, making it the recommended default validation strategy.

In summary, proper configuration of validation parameters—especially testOnBorrow —combined with sensible limits on pool size and abandonment handling, ensures both high performance and robust recovery of database connections.