diff --git a/documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc b/documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc index ce012faedb..1e6d399924 100644 --- a/documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc +++ b/documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc @@ -129,6 +129,39 @@ from the provider do not, in fact, have auto-commit disabled. Doing so will lead to Hibernate executing SQL operations outside of any JDBC/SQL transaction. ==== +`*hibernate.connection.handling_mode*`:: +Specifies how Hibernate should manage JDBC connections in terms of acquiring and releasing. +This configuration property supersedes `*hibernate.connection.acquisition_mode*` and +`*hibernate.connection.release_mode*`. ++ +The connection handling mode strategies are defined by the +https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/resource/jdbc/spi/PhysicalConnectionHandlingMode.html[`PhysicalConnectionHandlingMode`] enumeration. ++ +The configuration can be either a `PhysicalConnectionHandlingMode` reference or its case-insensitive `String` representation. ++ +For more details about the `PhysicalConnectionHandlingMode` and Hibernate connection handling, check out the +<> section. + +[line-through]#`*hibernate.connection.acquisition_mode*`# (e.g. `immediate`):: +[NOTE] +==== +This setting is deprecated. You should use the `*hibernate.connection.handling_mode*` instead. +==== ++ +Specifies how Hibernate should acquire JDBC connections. The possible values are given by `org.hibernate.ConnectionAcquisitionMode`. ++ +Should generally only configure this or `hibernate.connection.release_mode`, not both. + +[line-through]#`*hibernate.connection.release_mode*`# (e.g. `auto` (default value)):: +[NOTE] +==== +This setting is deprecated. You should use the `*hibernate.connection.handling_mode*` instead. +==== ++ +Specifies how Hibernate should release JDBC connections. The possible values are given by the current transaction mode (`after_transaction` for JDBC transactions and `after_statement` for JTA transactions). ++ +Should generally only configure this or `hibernate.connection.acquisition_mode`, not both. + `*hibernate.connection.datasource*`:: Either a `javax.sql.DataSource` instance or a JNDI name under which to locate the `DataSource`. + @@ -159,16 +192,6 @@ Names a prefix used to define arbitrary JNDI `javax.naming.InitialContext` prope + These properties are passed along to `javax.naming.InitialContext#InitialContext(java.util.Hashtable)` -`*hibernate.connection.acquisition_mode*` (e.g. `immediate`):: -Specifies how Hibernate should acquire JDBC connections. The possible values are given by `org.hibernate.ConnectionAcquisitionMode`. -+ -Should generally only configure this or `hibernate.connection.release_mode`, not both. - -`*hibernate.connection.release_mode*` (e.g. `auto` (default value)):: -Specifies how Hibernate should release JDBC connections. The possible values are given by the current transaction mode (`after_transaction` for JDBC transactions and `after_statement` for JTA transactions). -+ -Should generally only configure this or `hibernate.connection.acquisition_mode`, not both. - ==== Hibernate internal connection pool options `*hibernate.connection.initial_pool_size*` (e.g. 1 (default value)):: diff --git a/documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc b/documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc index b6ea92ca12..233bf3c070 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc @@ -187,6 +187,62 @@ Not that this is only supported for JDBC standard isolation levels, not for isol * a short-name version of the java.sql.Connection constant field without the `TRANSACTION_` prefix. For example, `REPEATABLE_READ` for https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html#TRANSACTION_REPEATABLE_READ[`java.sql.Connection#TRANSACTION_REPEATABLE_READ`]. Again, this is only supported for JDBC standard isolation levels, not for isolation levels specific to a particular JDBC driver. +[[database-connection-handling]] +=== Connection handling + +The connection handling mode is defined by the +https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/resource/jdbc/spi/PhysicalConnectionHandlingMode.html[`PhysicalConnectionHandlingMode`] enumeration which provides the following strategies: + +`IMMEDIATE_ACQUISITION_AND_HOLD`:: +The `Connection` will be acquired as soon as the `Session` is opened and held until the `Session` is closed. +`DELAYED_ACQUISITION_AND_HOLD`:: +The `Connection` will be acquired as soon as it is needed and then held until the `Session` is closed. +`DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT`:: +The `Connection` will be acquired as soon as it is needed and will be released after each statement is executed. +`DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION`:: +The `Connection` will be acquired as soon as it is needed and will be released after each transaction is completed. + +If you don't want to use the default connection handling mode, you can specify a connection handling mode via the `hibernate.connection.handling_mode` configuration property. For more details, check out the +<> section. + +==== Transaction type and connection handling + +By default, the connection handling mode is given by the underlying transaction coordinator. There are two types of transactions: `RESOURCE_LOCAL` (which involves a single database `Connection` and the transaction is controlled via the `commit` and `rollback` `Connection` methods) and `JTA` (which may involve multiple resources either database connections, JMS queues, etc). + +===== RESOURCE_LOCAL transaction connection handling + +For `RESOURCE_LOCAL` transactions, the connection handling mode is `DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION` meaning that the database connection is acquired when needed and released after the current running transaction is either committed or rolled back. + +However, because Hibernate needs to make sure that the default autocommit mode is disabled on the JDBC `Connection` +when starting a new transaction, the `Connection` is acquired and the autocommit mode is set to `false`. + +[NOTE] +==== +If you are using a connection pool `DataSource` that already disabled the autocommit mode for every pooled `Connection`, you can set the `hibernate.connection.provider_disables_autocommit` to `true` and the database connection acquisition will be, indeed, delayed until Hibernate needs to execute an SQL statement. +==== + +===== JTA transaction connection handling + +For `JTA` transactions, the connection handling mode is `DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT` meaning that the database connection is acquired when needed and released after each statement execution. + +The reason for releasing the database connection after statement execution is because some Java EE application servers +report a connection leak when a method call goes from one EJB to another. However, even if the JDBC `Connection` is released to the pool, the `Connection` is still allocated to the current executing `Thread`, hence when executing a subsequent statement in the current running transaction, the same `Connection` object reference will be obtained from the pool. + +[NOTE] +==== +If the Java EE application server or JTA transaction manager supports switching from one EJB to another while the transaction gets propagated from the outer EJB to the inner one, +and no connection leak false positive is being reported, then you should consider switching to `DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION` via the `hibernate.connection.handling_mode` configuration property. +==== + +==== User-provided connections + +If the current `Session` was created using the +https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/SessionBuilder.html[`SessionBuilder`] and a JDBC `Connection` was provided via the +https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/SessionBuilder.html#connection-java.sql.Connection-[`SessionBuilder#connection`] method, then the user-provided `Connection` is going to be used, and +the connection handling mode will be `IMMEDIATE_ACQUISITION_AND_HOLD`. + +Therefore for user-provided connection, the connection is acquired right away and held until the current `Session` is closed, without being influenced by the JPA or Hibernate transaction context. + [[database-dialect]] === Database Dialect