HHH-13012 - JDBC default connection release mode does not match documentation

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
+<<chapters/jdbc/Database_Access.adoc#database-connection-handling,Connection handling>> 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))::

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
+<<appendices/Configurations.adoc#configurations-database-connection,Database connection properties>> 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