Configuring JDBC Connection Pools

This documentation is only relevant for site admins who wish to apply custom configuration settings to manage their Postgres database connections. See XNAT Setup Options - Custom Configuration Settings for details.

In older versions of XNAT, there was only one option available for managing the PostgreSQL JDBC connection pool: the default DBCP2 Basic Data Source, or org.apache.commons.dbcp2.BasicDataSource.

As of XNAT 1.8.5, HikariCP was introduced as a new JDBC connection pool option. However, the DBCP2 Basic Data Source was still considered the default.

As of XNAT 1.9.0, HikariCP has been made the new default.

Administrators of XNATs for versions 1.8.5 and above can customize this behavior by modifying their xnat-conf.properties file, using the following settings.

Configuring the Datasource Class

Technically, the application’s datasource is not inherently a connection pool, but simply provides a way within the application to connect to the database without requiring any knowledge of the underlying database service, configuration, location, etc. That said, because the datasource is the primary interface between the application and its data, it’s up to the datasource implementation to manage the connections in such a way as to prevent gridlock and maximize resource utilization. That means that the datasource implementation is almost always a connection pool. XNAT provides two implementations internally:

HikariCP

HikariCP is only available in XNAT 1.8.5 and above. In XNAT 1.9 and above, HikariCP is the default setting and does not need to be specified.

Include this in your xnat-conf.properties file:

CODE

datasource.class=com.zaxxer.hikari.HikariDataSource

DBCP2

In XNAT 1.8.10.1 and earlier, DBCP2 is the default setting and does not need to be specified.

Include this in your xnat-conf.properties file:

CODE

datasource.class=org.apache.commons.dbcp2.BasicDataSource

Advanced Connection Pool Configuration

In addition to specifying the datasource class, you can also specify advanced configuration options. Both HikariCP and DBCP2 accept property maps (see here for HikariCP’s properties, here for DBCP2’s properties) on start-up that you can use to customize and tune the database connection pool.

All properties that should be passed from xnat-conf.propertiesto the datasource implementation on start-up must be prefaced with datasource., e.g. minimumIdlewould be specified as datasource.minimumIdle.

For ease of reading, the prefix is omitted in this section, but make sure you specify it for any properties you add to xnat-conf.properties.

The following properties are the same whether you’re using HikariCP or DBCP2:

Property	Default	Description
class	`com.zaxxer.hikari.HikariDataSource`	Specifies the class to use for the datasource implementation.
driver	`org.postgresql.Driver`	This usually doesn’t need to be configured.
username	`xnat`	The username for accessing the database.
password	`xnat`	The password for accessing the database.

The following properties differ between HikariCP and DBCP2, but XNAT translates these properties to the appropriate property for the specified implementation, i.e. if you specify a HikariCP property name like jdbcUrl but set class to use DBCP2, XNAT translates that to url.

HikariCP	DBCP2	Default	Description
jdbcUrl	url	`jdbc:postgresql://localhost/xnat`	URL for accessing the database instance.
minimumIdle	initialSize	20	Minimum number of connections to maintain in the connection pool.
maximumPoolSize	maxTotal	40	Maximum number of connections to allow in the connection pool.
N/A	maxIdle	10	Maximum number of idle connections allowed in the pool before connections are released and pool size reduced. There is no equivalent setting for this for HikariCP.

You can also set any other properties supported by the datasource implementation simply by setting the relevant properties (prefixed with “datasource."!) in xnat-conf.properties. For example, if you’re using HikariCP and want to set the idle timeout to one minute, you could set this:

CODE

datasource.idleTimeout=60000

Note that XNAT performs no validation on any properties or their values, but just passes anything prefaced with the appropriate prefix onto the datasource implementation upon start-up.