As the lead of a Spring Boot service using jOOQ, would you standardise on @Transactional or on dsl.transactionResult, and how would you enforce it?
answer
- two boundaries, one connection
- same call, different meaning by caller
- savepoint tool versus commit tool
- write the rule, then test for it
- a provider bean can fail fast
basics
~20 sPick one model per codebase. In a Spring Boot service, @Transactional usually owns boundaries and transactionResult, which Boot turns into a nested savepoint, is allowed only as a deliberate savepoint step; enforce it with an architecture test and failure-path integration tests.
solid answer
~50 sI would pick one model and write down its exceptions. For a typical Spring Boot service, Spring owns boundaries: `@Transactional` covers jOOQ and any other access on the same `DataSource`, and keeps isolation, read-only and timeouts in one place. Under Boot, `transactionResult` runs on `SpringTransactionProvider` with `PROPAGATION_NESTED`, so inside a Spring transaction it is a savepoint and it ignores isolation arguments; I would allow it only as a named "try this step, keep the rest" tool. A codebase that must also run without Spring transaction management can instead standardise on `transactionResult` and pass `cfg.dsl()` down explicitly. Mixing without a rule is the defect, because the same call commits in one caller and only sets a savepoint in another. I would enforce it with an architecture test on where `transactionResult` may be called, and integration tests that force a failure. This assumes jOOQ 3.21 with Spring Boot 4.1.
go deeper
Recall that a Spring Boot service with jOOQ can mark boundaries with @Transactional or with transactionResult, and that teams usually pick one.
Explain why transactionResult under Boot is a savepoint inside @Transactional and a full transaction outside it, which is why mixing confuses readers.
Use concrete failure cases, such as ignored isolation, NestedTransactionNotSupportedException and thread hops, to show what an unruled mix costs in production.
Choose the default model from where the code must run, name the allowed exceptions, and back the rule with an architecture test, a fail-fast provider where useful and failure-path tests.
## The decision A Spring Boot service using jOOQ has two ways to draw a transaction boundary: Spring's `@Transactional` (or `TransactionTemplate`) and jOOQ's `dsl.transactionResult(...)`. Under Boot's auto-configuration both work and both reach the same connection, which is exactly why teams drift into using both. The lead's job is to pick **one model as the default**, define the narrow exceptions, and make the choice checkable. There is no universally right model; the right default follows from where the code must run and who has to read it. ## Option A: Spring owns transactions - **How it looks.** Service methods carry `@Transactional`; repositories inject `DSLContext` and run statements; nobody calls `transactionResult` outside named cases. - **Why it fits most Boot services.** One boundary covers jOOQ, any other JDBC access on the same `DataSource`, and Spring's transaction synchronisation, such as after-commit callbacks. Isolation, read-only and timeouts are declared in one place. - **What `transactionResult` is reduced to.** Under Boot it runs on `SpringTransactionProvider`, which requests `PROPAGATION_NESTED`: inside a Spring transaction it is a **savepoint**, outside one it is an ordinary transaction. A rule can allow it only as an explicit "try this step, keep the rest on failure" savepoint. - **Costs.** Boundaries are implicit and applied by a proxy, so where a method sits matters, and the declarative model's own pitfalls have to be taught. ## Option B: jOOQ owns transactions - **How it looks.** Use cases call `dsl.transactionResult(cfg -> ...)` and pass `cfg.dsl()` down to the code that runs statements; no `@Transactional`. - **Where it fits.** A codebase that wants boundaries visible in code, a batch or command-line module without Spring transaction management, or a shared library that must also run on jOOQ's `DefaultTransactionProvider`. - **Costs.** Every method that touches the database needs the transaction's context passed in. Isolation and read-only are set per call through `TransactionProperty`, and under Boot's `SpringTransactionProvider` those arguments are ignored, so this model is cleanest where Spring transaction management is not in play, for example with your own `TransactionProvider` bean or a context built without Boot. ## What mixing costs Mixing without a rule is the real defect, because the same line of code means different things depending on its caller: | Situation | What a reader expects | What happens under Boot | |---|---|---| | `transactionResult` called from an `@Transactional` method | an independent commit | a savepoint; nothing commits until the outer method returns | | `transactionResult(callable, Isolation.SERIALIZABLE)` | serializable isolation | the argument is ignored by `SpringTransactionProvider` | | `transactionResult` with a transaction manager that disallows nesting | it works | `NestedTransactionNotSupportedException` inside an outer transaction | | work handed to another thread inside either boundary | the same transaction | a separate pooled connection, outside it | ## Making the rule stick 1. **Write it down** in the service's conventions: which model, and the named exceptions, for example "savepoint steps through `transactionResult` only in classes that own a partial-failure use case". 2. **Enforce it statically** with an architecture test that fails the build when `DSLContext.transactionResult` or `DSLContext.transaction` is called outside allow-listed packages, or when `@Transactional` appears in a module that chose Option B. 3. **Fail fast at runtime where it is cheap.** Boot's `SpringTransactionProvider` backs off when you declare your own `TransactionProvider` bean. If the rule allows no savepoint steps at all, a provider that delegates to Spring's but rejects calls while `TransactionSynchronizationManager.isActualTransactionActive()` is true turns an accidental nested call into an immediate error. 4. **Test the failure path.** An integration test that forces a constraint violation in the inner step and asserts which rows survive catches a misunderstanding that no happy-path test will. ## Signals that the rule is failing - reviews keep asking "does this commit here?"; - isolation arguments appear on `transactionResult` calls in a Boot module; - incident reports describe rows that "should have been rolled back" or "should have survived"; - a `NestedTransactionNotSupportedException` appears after a module with a different transaction manager is added beside the jOOQ code. ## A defensible default For a Spring Boot service, default to Spring-managed boundaries and treat `transactionResult` as a savepoint tool that needs a stated reason; choose jOOQ-managed boundaries when the code must also run without Spring transaction management. Either way, one model per codebase, with the reason recorded, is what lets a reviewer tell where a commit happens. The behaviour described assumes jOOQ 3.21 with Spring Boot 4.1's jOOQ module.
- A team insists transactionResult reads better than annotations; when would you agree to Option B in a Spring Boot service?When the persistence code must also run without Spring transaction management, for example a shared module used by a batch tool, or when the team is willing to replace Boot's provider so that `transactionResult` means a real top-level transaction everywhere. Agreeing means removing `@Transactional` from that module, not adding a second model beside it.
- How would you migrate a codebase that already mixes both models?Inventory every `transactionResult` call and classify it by caller: calls always under `@Transactional` are savepoints and should become named savepoint steps or plain statements; calls never under one keep their meaning. Add the architecture test in warning mode, fix the list, then make it fail the build, with failure-path tests on each changed use case.
- Using both models freely is fine, because Boot makes them share one connection anyway.
- transactionResult is always the safer choice because it commits exactly where the code says.
- Isolation can be set per block with transactionResult arguments in a Spring Boot service.
- The rule needs no tests; code review alone will catch a misplaced boundary.
- There is one correct answer: annotation-driven transactions in every jOOQ codebase.
Assumes jOOQ 3.21 with Spring Boot 4.1's jOOQ module, where transactionResult runs on SpringTransactionProvider with PROPAGATION_NESTED.