diff --git a/src/main/asciidoc/jdbc.adoc b/src/main/asciidoc/jdbc.adoc index 28821569b..d8aa77e5c 100644 --- a/src/main/asciidoc/jdbc.adoc +++ b/src/main/asciidoc/jdbc.adoc @@ -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.