transactional-patterns

Transactional Patterns

Use When

• Configuring @Transactional propagation, sagas, or after-commit side effects
• Spring Boot code generation or refactor where agent defaults would be wrong

Workflow

1. Confirm the change matches this skill's domain triggers before coding.
2. Follow the domain guide conventions and gotchas below — not generic Spring Boot defaults.
3. Apply project-specific response envelopes, DTO boundaries, and dependency injection rules.
4. Validate with targeted tests (slice, integration, or contract as appropriate).
5. Capture evidence before merge: tests, migration notes, or observability proof.

Required Checks

• Constructor injection used; no @Autowired field injection on new code
• Controllers return DTOs/envelopes — never raw JPA entities
• Business logic stays in @Service layer, not controllers or repositories
• Error handling uses project-standard envelope or RFC 9457 ProblemDetail

Domain Guide

Basic Rules

• @Transactional belongs on service methods, never controllers or repositories
• Default propagation is REQUIRED — joins existing transaction or creates one
• Always use on methods that write to the DB or coordinate multiple writes
• @Transactional(readOnly = true) on all read-only service methods — enables optimizations

@Service
@RequiredArgsConstructor
@Transactional(readOnly = true) // default for all methods in this service
public class OrderService {

    @Transactional // overrides readOnly for writes
    public Order createOrder(CreateOrderRequest request) {
        inventoryService.reserve(request.items()); // participates in same TX
        return orderRepository.save(Order.from(request));
    }

    public Optional<Order> findById(UUID id) {
        return orderRepository.findById(id); // readOnly = true inherited
    }
}

Propagation

Propagation	Behavior
REQUIRED (default)	Join existing TX or create new
REQUIRES_NEW	Always create new TX, suspend existing
SUPPORTS	Join if exists, proceed without TX if not
NOT_SUPPORTED	Always run without TX
MANDATORY	Must have existing TX, throw if not
NEVER	Must NOT have TX, throw if one exists