HowTo configure the C3P0 connection pool

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.

Regards,

Anthony

(see http://forum.hibernate.org/viewtopic.php?t=934779 for more details)


--------------------------------------------------------------------------------

If you want to get rid of the C3P0 status that is printed, by default, when hibernate starts, you need to recompile C3P0 sources after changing com.mchange.v2.c3p0.Debug.DEBUG to false.

This is a public static final field that cannot be changed by configuration files.

Hibernate's C3P0ConnectionProvider explicitly sets 7 c3p0 configuration properties, based on your hibernate configuration, overriding any configuration you may have set in a c3p0.properties file. If you are using Hibernate's C3P0ConnectionProvider you must set the following properties in your hibernate configuration, using hibernate-specific configuration keys. All other properties must be defined as usual in a c3p0.properties file. This is confusing, and will hopefully be simplified some time in the future, but for now...

The following properties must be set in your hibernate configuration:

c3p0-native property name hibernate configuration key 
c3p0.acquireIncrement hibernate.c3p0.acquire_increment 
c3p0.idleConnectionTestPeriod hibernate.c3p0.idle_test_period 
c3p0.initialPoolSize not available -- uses minimum size 
c3p0.maxIdleTime hibernate.c3p0.timeout 
c3p0.maxPoolSize hibernate.c3p0.max_size 
c3p0.maxStatements hibernate.c3p0.max_statements 
c3p0.minPoolSize hibernate.c3p0.min_size 
c3p0.testConnectionsOnCheckout  hibernate.c3p0.validate hibernate 2.x only! 

Remember -- these, and only these, properties must be defined in your hibernate configuration, or else they will be set to hibernate-specified defaults. All other configuration properties that you wish to set should be defined in a c3p0.properties file. (See "Overriding c3p0 defaults via c3p0.properties".)