Clarify transactional defaults and recommendations.
Closes
@@ -920,7 +920,7 @@ Thus, if you want to inspect what SQL statements are run, activate logging for S
[[jdbc.transactions]]
== Transactionality
-CRUD methods on repository instances are transactional by default.
+The methods of `CrudRepository` instances are transactional by default.
For reading operations, the transaction configuration `readOnly` flag is set to `true`.
All others are configured with a plain `@Transactional` annotation so that default transaction configuration applies.
For details, see the Javadoc of link:{javadoc-base}org/springframework/data/jdbc/repository/support/SimpleJdbcRepository.html[`SimpleJdbcRepository`].
@@ -1008,7 +1008,11 @@ Typically, you want the `readOnly` flag to be set to true, because most of the q
In contrast to that, `deleteInactiveUsers()` uses the `@Modifying` annotation and overrides the transaction configuration.
Thus, the method is with the `readOnly` flag set to `false`.
-NOTE: It is definitely reasonable to use transactions for read-only queries, and we can mark them as such by setting the `readOnly` flag.
+NOTE: It is highly recommended to make query methods transactional. These methods might execute more then one query in order to populate an entity.
+Without a common transaction Spring Data JDBC executes the queries in different connections.
+This may put excessive strain on the connection pool and might even lead to dead locks when multiple methods request a fresh connection while holding on to one.
+
+NOTE: It is definitely reasonable to mark read-only queries as such by setting the `readOnly` flag.
This does not, however, act as a check that you do not trigger a manipulating query (although some databases reject `INSERT` and `UPDATE` statements inside a read-only transaction).
Instead, the `readOnly` flag is propagated as a hint to the underlying JDBC driver for performance optimizations.
