HowTo configure the C3P0 connection pool

• Configuration
• Parameters

Configuration

Here is a sample of C3P0 configuration. This is an extract of hibernate.cfg.xml:

<!-- configuration pool via c3p0--> 
<property name="c3p0.acquire_increment">1</property> 
<property name="c3p0.idle_test_period">100</property> <!-- seconds --> 
<property name="c3p0.max_size">100</property> 
<property name="c3p0.max_statements">0</property> 
<property name="c3p0.min_size">10</property> 
<property name="c3p0.timeout">100</property> <!-- seconds --> 
<!-- DEPRECATED very expensive property name="c3p0.validate>--> 

You also can set extra c3p0 properties using c3p0.properties. Put this file in the classpath (WEB-INF/classes for example), but be careful, the previous values will be overridden by Hibernate whether set or not (see below for more details). For more information on C3P0 configuration, please have a look at http://sourceforge.net/projects/c3p0 and unzip the download, there is a doc folder where you'll find everything you need.

For more on hibernate/c3p0 issues, see c3p0's docs at http://www.mchange.com/projects/c3p0/index.html#appendix_d

Parameters

c3p0 is very tunable, and offers a somewhat bewildering array of configuration parameters. For the complete list, see http://www.mchange.com/projects/c3p0/index.html#appendix_a

Here are a subset of the most important features:

initialPoolSize C3P0 default: 3

minPoolSize Must be set in hibernate.cfg.xml (or hibernate.properties), Hibernate default: 1

maxPoolSize Must be set in hibernate.cfg.xml (or hibernate.properties), Hibernate default: 100

idleTestPeriod Must be set in hibernate.cfg.xml (or hibernate.properties), Hibernate default: 0

If this is a number greater than 0, c3p0 will test all idle, pooled but unchecked-out connections, every this number of seconds.

timeout Must be set in hibernate.cfg.xml (or hibernate.properties), Hibernate default: 0

The seconds a Connection can remain pooled but unused before being discarded. Zero means idle connections never expire.

maxStatements Must be set in hibernate.cfg.xml (or hibernate.properties), Hibernate default: 0

The size of c3p0's PreparedStatement cache. Zero means statement caching is turned off.

propertyCycle Must be set in c3p0.properties, C3P0 default: 300

Maximum time in seconds before user configuration constraints are enforced. c3p0 enforces configuration constraints continually, and ignores this parameter. It is included for JDBC3 completeness.

acquireIncrement Must be set in hibernate.cfg.xml (or hibernate.properties), Hibernate default: 1

Determines how many connections at a time c3p0 will try to acquire when the pool is exhausted.

testConnectionOnCheckout Must be set in c3p0.properties, C3P0 default: false

Don't use it, this feature is very expensive. If set to true, an operation will be performed at every connection checkout to verify that the connection is valid. A better choice is to verify connections periodically using c3p0.idleConnectionTestPeriod.

autoCommitOnClose Must be set in c3p0.properties, C3P0 default: false

The JDBC spec is unfortunately silent on what should happen to unresolved, pending transactions on Connection close. C3P0's default policy is to rollback any uncommitted, pending work. (I think this is absolutely, undeniably the right policy, but there is no consensus among JDBC driver vendors.) Setting autoCommitOnClose to true causes uncommitted pending work to be committed, rather than rolled back on Connection close. [Note: Since the spec is absurdly unclear on this question, application authors who wish to avoid bugs and inconsistent behavior should ensure that all transactions are explicitly either committed or rolled-back before close is called.]

forceIgnoreUnresolvedTransactions Must be set in c3p0.properties, C3P0 default: false

Strongly disrecommended. Setting this to true may lead to subtle and bizarre bugs. This is a terrible setting, leave it alone unless absolutely necessary. It is here to work around broken databases / JDBC drivers that do not properly support transactions, but that allow Connections' autoCommit flags to be set to false regardless. If you are using a database that supports transactions "partially" (this is oxymoronic, as the whole point of transactions is to perform operations reliably and completely, but nevertheless, such databases exist), if you feel comfortable ignoring the fact that Connections with autoCommit == false may be in the middle of transactions and may hold locks and other resources, you may turn off c3p0's wise default behavior, which is to protect itself, as well as the usability and consistency of the database, by either rolling back (default) or committing (see c3p0.autoCommitOnClose above) unresolved transactions. This should only be set to true when you are sure you are using a database that allows Connections' autoCommit flag to go to false, but that it offers no other meaningful support of transactions. Otherwise setting this to true is just a bad idea.

numHelperThreads Must be set in c3p0.properties, C3P0 default: 3

c3p0 is very asynchronous. Slow JDBC operations are generally performed by helper threads that don't hold contended locks. Spreading these operations over multiple threads can significantly improve performance by allowing multiple operations to be performed simultaneously.

factoryClassLocation Must be set in c3p0.properties, C3P0 default: null

DataSources that will be bound by JNDI and use that API's Referenceable interface to store themselves may specify a URL from which the class capable of dereferencing a them may be loaded. If (as is usually the case) the c3p0 libraries will be locally available to the JNDI service, leave this set to null.