Transaction Boundary Reviewer

Transaction Boundary Reviewer

When to Use / When Not to Use

Use when:

• Data appears inconsistent after partial failures
• Transactions are causing lock contention or timeout errors under load
• Two writes (possibly across services) need atomicity
• Reviewing @Transactional boundaries in Spring Boot code

Do not use when:

• The issue is slow SQL queries (use sql-pro)
• Connection pool exhaustion is the root cause (use connection-pool-tuner)

Process

1. Identify which ACID property is at risk — Atomicity (partial writes), Isolation (concurrent anomaly), Consistency (constraint bypass), or Durability (premature ack)
2. Map the transaction boundary — What code runs inside @Transactional? Does it include external I/O?
3. Check for common anti-patterns — Wide transactions, N+1 inside transactions, missing rollbackFor, lost updates
4. Select isolation level — Choose the lowest level that prevents the specific anomaly
5. Apply the right distributed pattern — Outbox (event publishing), Saga (long-running flows), or pessimistic/optimistic locking

For full Outbox and Saga implementations, see references/distributed-patterns.md.

Output Template

For each review, provide:

1. ACID property at risk (with diagnosis)
2. Anti-patterns found (with code evidence)
3. Corrected code or pattern
4. Isolation level recommendation with rationale
5. For cross-service: Outbox or Saga pattern recommendation

What Claude Does / What You Do

ACID Properties Reference

Isolation Levels

Common Anti-Patterns

1. Overly Wide Transactions

// Bad — HTTP call inside transaction holds locks
@Transactional
public void processOrder(Order order) {
    orderRepository.save(order);
    paymentGateway.charge(order);  // external HTTP — locks held during this!
}

// Good — database work is atomic; side effects happen after commit
@Transactional
public Order saveOrder(Order order) { return orderRepository.save(order); }

public void processOrder(Order order) {
    Order saved = saveOrder(order);     // transaction commits here
    paymentGateway.charge(saved);       // no locks held
}

2. Missing Rollback on Checked Exceptions

// Bad — IOException does NOT trigger rollback in Spring by default
@Transactional
public void importData(File file) throws IOException { ... }

// Good — explicit rollback declaration
@Transactional(rollbackFor = IOException.class)
public void importData(File file) throws IOException { ... }

3. Lost Update (Read Inside Write)

// Bad — two threads read balance=100, both deduct 80, both save 20
@Transactional
public void deduct(Long accountId, BigDecimal amount) {
    Account account = accountRepo.findById(accountId).orElseThrow();
    account.setBalance(account.getBalance().subtract(amount));
    accountRepo.save(account);
}

// Good — pessimistic lock (SELECT FOR UPDATE)
@Transactional
public void deduct(Long accountId, BigDecimal amount) {
    Account account = accountRepo.findByIdWithLock(accountId).orElseThrow();
    account.setBalance(account.getBalance().subtract(amount));
    accountRepo.save(account);
}

4. Distributed Transaction Anti-Patterns

Review Checklist

• No external I/O (HTTP, email, Kafka publish) inside database transactions
• N+1 queries in transactions replaced with batch fetches
• @Transactional rollbackFor covers checked exceptions that should rollback
• Concurrent read-modify-write paths use pessimistic or optimistic locking
• Cross-service writes use Outbox or Saga, not XA/2PC
• Isolation level matches the anomaly being prevented
• Transaction boundaries align with domain aggregate boundaries

Related Skills

• spring-boot-engineer — for implementing the corrected @Transactional patterns
• microservices-architect — when the issue is cross-service transaction design
• circuit-breaker-tuner — wide transactions compound cascading failure risk
• connection-pool-tuner — wide transactions can exhaust the connection pool