11.5. Connection release modes
One of the legacies of Hibernate 2.x JDBC connection management meant that a
Session
would obtain a connection when it was first required and then maintain that connection until the session was closed. Hibernate 3.x introduced the notion of connection release modes that would instruct a session how to handle its JDBC connections. The following discussion is pertinent only to connections provided through a configured ConnectionProvider
. User-supplied connections are outside the breadth of this discussion. The different release modes are identified by the enumerated values of org.hibernate.ConnectionReleaseMode
:
ON_CLOSE
: is the legacy behavior described above. The Hibernate session obtains a connection when it first needs to perform some JDBC access and maintains that connection until the session is closed.AFTER_TRANSACTION
: releases connections after aorg.hibernate.Transaction
has been completed.AFTER_STATEMENT
(also referred to as aggressive release): releases connections after every statement execution. This aggressive releasing is skipped if that statement leaves open resources associated with the given session. Currently the only situation where this occurs is through the use oforg.hibernate.ScrollableResults
.
The configuration parameter
hibernate.connection.release_mode
is used to specify which release mode to use. The possible values are as follows:
auto
(the default): this choice delegates to the release mode returned by theorg.hibernate.transaction.TransactionFactory.getDefaultReleaseMode()
method. For JTATransactionFactory, this returns ConnectionReleaseMode.AFTER_STATEMENT; for JDBCTransactionFactory, this returns ConnectionReleaseMode.AFTER_TRANSACTION. Do not change this default behavior as failures due to the value of this setting tend to indicate bugs and/or invalid assumptions in user code.on_close
: uses ConnectionReleaseMode.ON_CLOSE. This setting is left for backwards compatibility, but its use is discouraged.after_transaction
: uses ConnectionReleaseMode.AFTER_TRANSACTION. This setting should not be used in JTA environments. Also note that with ConnectionReleaseMode.AFTER_TRANSACTION, if a session is considered to be in auto-commit mode, connections will be released as if the release mode were AFTER_STATEMENT.after_statement
: uses ConnectionReleaseMode.AFTER_STATEMENT. Additionally, the configuredConnectionProvider
is consulted to see if it supports this setting (supportsAggressiveRelease()
). If not, the release mode is reset to ConnectionReleaseMode.AFTER_TRANSACTION. This setting is only safe in environments where we can either re-acquire the same underlying JDBC connection each time you make a call intoConnectionProvider.getConnection()
or in auto-commit environments where it does not matter if we re-establish the same connection.