Ankur Mhatre
585eed4d57
The repository now aggregates two independent modules. migration-behavior/ is the
original project, moved unchanged; it stays on Spring Boot 4.0.6 / JDK 21 because
that is what the four published migration articles were verified against, and
upgrading it would silently invalidate output they quote. The article-tagged trees
are untouched, so links into a tag are unaffected.
transactions/ Companion code for "@Transactional in Spring: Propagation, Isolation,
and the Six Ways It Silently Does Nothing". Spring Boot 4.1.1 / JDK 25.
Every row of the propagation matrix is produced by calling the method and asking the
transaction manager what it did. The transaction NAME is the exhibit: a scope that
joined reports its caller's name, a scope that started its own reports its own.
Three things the transcripts settle:
- Propagation.NESTED cannot be used with JpaTransactionManager. It fails twice,
with two different messages, the second of which blames your JPA provider. The
savepoint manager comes from the object the JpaDialect returns when it begins the
transaction, and Hibernate's does not implement one. It works on
DataSourceTransactionManager, because a savepoint is a JDBC concept -- shown
working there rather than only failing here.
- Catching a REQUIRED inner failure does not save the transaction. The inner scope
has already marked it rollback-only, so the commit throws
UnexpectedRollbackException from a place with no connection to the cause.
- A checked exception commits, and so does a swallowed one. Those two do not merely
fail to start a transaction; they commit work the code was abandoning.
19 contract tests, six captured transcripts, all regenerated by scripts/run-all.sh.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gip4srpzMwjgoba6uEfbr5
3.4 KiB
← What @Transactional does · Index · Rollback →
2. The seven propagation values
Transcript: 01-propagation.txt. Every row was produced by calling
the method, not by reading the enum.
| Propagation | Caller has a transaction | Caller has none |
|---|---|---|
REQUIRED (default) |
joins it | starts one |
REQUIRES_NEW |
suspends it, starts its own | starts one |
NESTED |
savepoint — fails on JPA, see chapter 4 | starts one |
SUPPORTS |
joins it | runs with no transaction |
NOT_SUPPORTED |
suspends it, runs with none | runs with none |
MANDATORY |
joins it | IllegalTransactionStateException |
NEVER |
IllegalTransactionStateException |
runs with none |
The measured version
PROPAGATION CALLER ACTIVE TRANSACTION NAME / OUTCOME
----------------------------------------------------------------------------
REQUIRED inside @Transactional True inTransaction
REQUIRED no transaction True required
REQUIRES_NEW inside @Transactional True requiresNew
NESTED inside @Transactional -- NestedTransactionNotSupportedException
SUPPORTS inside @Transactional True inTransaction
SUPPORTS no transaction False supports
NOT_SUPPORTED inside @Transactional False notSupported
MANDATORY no transaction -- IllegalTransactionStateException
NEVER inside @Transactional -- IllegalTransactionStateException
Read the name column. REQUIRED inside a transaction reports inTransaction — the
caller's method — because it joined. REQUIRES_NEW reports requiresNew — its own — because
it started a second physical transaction.
Notes that matter in practice
SUPPORTS with no transaction is not "no writes". The method still runs and still writes;
the write just lands on an auto-commit connection with no rollback available. SUPPORTS is for
read paths that do not care, and it is a poor default for anything that mutates.
NOT_SUPPORTED suspends, it does not merely decline. The caller's transaction is set aside
and restored afterwards. Suspension holds the outer connection open while the inner work runs.
REQUIRES_NEW needs two connections at once. The outer transaction keeps its connection
while the inner one takes another. A pool sized to the number of request threads will deadlock
under load — size it to exceed concurrent threads by at least one, per request nesting level.
MANDATORY is an assertion. Use it on a helper that must never be called outside a
transaction; it turns a silent correctness bug into a startup-visible exception.
NEVER is rare and usually means the work should be somewhere else entirely.
Exact messages
NESTED NestedTransactionNotSupportedException:
Transaction manager does not allow nested transactions by default -
specify 'nestedTransactionAllowed' property with value 'true'
MANDATORY IllegalTransactionStateException:
No existing transaction found for transaction marked with propagation 'mandatory'
NEVER IllegalTransactionStateException:
Existing transaction found for transaction marked with propagation 'never'