Tomcat Pool Configurations

This page explains the Tomcat JDBC connection pool configuration used for OpenSpecimen. Understanding these parameters helps in tuning performance, stability, and troubleshooting database connectivity issues.

Resource Definition

The following resource is defined in Tomcat (usually in context.xml)

<Resource name="jdbc/openspecimen" auth="Container" type="javax.sql.DataSource"
    factory="org.apache.tomcat.jdbc.pool.DataSourceFactory" testWhileIdle="true" testOnBorrow="true"
    validationQuery="select 1 from dual" validationInterval="60000" timeBetweenEvictionRunsMillis="60000"
    minEvictableIdleTimeMillis="60000" maxActive="100" minIdle="10" initialSize="10" maxWait="10000"
    removeAbandoned="true" removeAbandonedTimeout="300" logAbandoned="true" jmxEnabled="true" abandonWhenPercentageFull="60"
    jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer" 
    username="<DB_USER>" password="<DB_PASSWORD>"
    driverClassName="<DRIVER_NAME>"
    url="jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}?${ANY_OTHER_PARAMS}"
/>

This configures a JDBC DataSource managed by Tomcat using its built-in connection pool.

DataSource Configuration Parameters

Category	Parameter	Value	Description

Category	Parameter	Value	Description
Validation	testWhileIdle	true	Validates idle connections periodically to keep the pool clean and healthy
Validation	testOnBorrow	true	Ensures the connection is validated before it is handed to the application
Validation	validationQuery	select 1 from dual	Lightweight query to verify connection health
Validation	validationInterval	60000	Each connection is validated at most once every 60 seconds
Eviction	timeBetweenEvictionRunsMillis	60000	Interval between eviction runs for idle or abandoned connections
Eviction	minEvictableIdleTimeMillis	60000	Maximum idle time before a connection is eligible for removal
Pool Size	maxActive	100	Maximum number of active connections allowed
Pool Size	minIdle	10	Minimum number of idle connections maintained
Pool Size	initialSize	10	Number of connections created when the pool starts
Pool Size	maxWait	10000	Maximum time (ms) to wait for a connection before timing out
Abandoned	removeAbandoned	true	Enables detection and removal of leaked connections
Abandoned	removeAbandonedTimeout	300	Connections not returned within 5 minutes are closed and removed
Abandoned	logAbandoned	true	Logs stack traces for abandoned connections
Abandoned	abandonWhenPercentageFull	60	trigger abandoned connection cleanup only when the pool is 60% full (or more).
Monitoring	jmxEnabled	true	Enables JMX monitoring for the connection pool
Interceptors	jdbcInterceptors	`ConnectionState, StatementFinalizer`	Optimizes connection state handling and ensures statements are closed
Connectivity	driverClassName	`com.mysql.cj.jdbc.Driver` /`oracle.jdbc.OracleDriver`	MySQL JDBC driver / Oracle JDBC Driver
Connectivity	url	`jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}` / `jdbc:oracle:thin:@//HOST:PORT/SERVICE_NAME`	MySQL Database connection URL / Oracle Database URL
Connectivity	username	`${DB_USER}`	Database username
Connectivity	password	`${DB_PASSWORD}`	Database password