Spring Transaction Management: The Production Guide You Can't Afford to Ignore

I've been debugging transaction issues in production for over a decade, and here's the hard truth: most teams get this wrong. Whether it's a deadlock in a high-traffic payment system or a silent data corruption in a billing pipeline, transaction management is where the rubber meets the road. This guide covers Spring Boot 3.2.0+, Hibernate 6.3.1.Final, and Spring Security 6.x, with real stack traces from incidents I've personally handled. By the end, you'll know exactly how to avoid the traps that have burned countless teams.

1. Core Concepts and Configuration

Let's start with the foundation. In Spring Boot 3.2+, transaction management is auto-configured when you include spring-boot-starter-data-jpa. The default transaction manager is JpaTransactionManager, backed by Hibernate 6.3.1.Final. You can verify this by checking your application.properties:

``properties spring.jpa.properties.hibernate.current_session_context_class=org.springframework.orm.hibernate5.SpringSessionContext ``

The @Transactional annotation is the cornerstone. It can be applied at the class or method level. When placed on a class, all public methods inherit the transaction configuration. But here's the trap: private methods are ignored because Spring uses proxies. If you call a private method from a public one, the transaction won't propagate.

Let me be blunt: if you're using @Transactional on private methods, you're doing it wrong. Spring's proxy-based AOP can't intercept private calls. Use @Transactional only on public methods, or switch to AspectJ weaving for full support.

Here's the proper configuration for a service layer:

```java @Service @Transactional public class PaymentService { @Autowired private PaymentRepository paymentRepository;

public void processPayment(Payment payment) { // This method is transactional paymentRepository.save(payment); } } ```

I've seen this blow up in production when a developer added @Transactional to a private helper method and expected it to create a new transaction. It didn't. The database ended up with partial writes, and we spent two days tracing the issue.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.datasource.DataSourceTransactionManager;
import org.springframework.transaction.PlatformTransactionManager;
import javax.sql.DataSource;

@Configuration
public class TransactionConfig {

    @Bean
    public PlatformTransactionManager transactionManager(DataSource dataSource) {
        DataSourceTransactionManager manager = new DataSourceTransactionManager(dataSource);
        manager.setNestedTransactionAllowed(true); // For nested transactions
        return manager;
    }
}

2. What the Official Docs Won't Tell You

The official Spring documentation covers the basics well, but it glosses over the production realities. Here's what they won't tell you:

First, @Transactional with readOnly = true is not a silver bullet for performance. In Hibernate 6.3, setting readOnly = true does NOT disable dirty checking entirely. It only sets FlushMode.NEVER and skips the flush at commit time. But the persistence context still tracks changes. If you modify an entity, Hibernate will still detect it and throw a HibernateException on flush. I've seen teams add readOnly = true thinking it would make queries faster, only to get confusing errors.

Second, propagation levels like REQUIRES_NEW are a trap that will burn you. When you use REQUIRES_NEW, the current transaction is suspended and a new one starts. If the new transaction commits but the outer one rolls back, the inner transaction's changes are already committed. This is a common source of data inconsistency in batch processing.

Third, the default rollback behavior is for unchecked exceptions (RuntimeException and Error) only. Checked exceptions (like SQLException) do NOT trigger rollback unless you explicitly specify rollbackFor. I've seen this blow up in production when a team used checked exceptions for business logic failures, expecting automatic rollback. The result: partial commits that corrupted financial data.

Stop doing this: relying on default rollback behavior without understanding exception hierarchies. Always specify rollbackFor and noRollbackFor explicitly in production code.

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

@Service
public class OrderService {

    @Autowired
    private InvoiceService invoiceService;

    @Transactional(rollbackFor = Exception.class)
    public void createOrder(Order order) {
        // Save order
        try {
            invoiceService.generateInvoice(order); // REQUIRES_NEW
        } catch (Exception e) {
            // Outer transaction will rollback, but inner is already committed!
            throw new RuntimeException("Order failed", e);
        }
    }
}

@Service
public class InvoiceService {

    @Transactional(propagation = Propagation.REQUIRES_NEW, rollbackFor = Exception.class)
    public void generateInvoice(Order order) {
        // This runs in a separate transaction
        // If this commits, it stays committed even if outer rolls back
    }
}

3. Propagation Levels Demystified

Propagation levels define how transactions relate to each other when one transactional method calls another. Spring supports seven levels, but only a few are commonly used. Let's cut through the noise.

REQUIRED (default): If a transaction exists, join it; otherwise, create a new one. This is the safest choice for most operations.

REQUIRES_NEW: Suspend the current transaction and create a new one. As I said, this is a trap that will burn you. Use only when you need independent transaction boundaries, like logging audit trails.

NESTED: Uses a savepoint within the current transaction. If the nested transaction rolls back, the outer transaction can choose to commit or rollback. This is safer than REQUIRES_NEW for partial rollbacks.

MANDATORY: Requires an existing transaction; throws an exception if none exists. Useful for methods that must be called within a transactional context.

NEVER: Ensures no transaction exists; throws an exception if one does. Rarely used.

SUPPORTS: If a transaction exists, join it; otherwise, run non-transactionally. Risky because partial changes can be committed.

NOT_SUPPORTED: Suspend any existing transaction and run non-transactionally. Use for methods that shouldn't be transactional, like sending notifications.

I've seen this blow up in production when a team used MANDATORY on a service method but forgot to start a transaction at the controller level. The result: IllegalTransactionStateException in production. The fix was to add @Transactional at the controller or use REQUIRED instead.

Let me be blunt: 90% of your use cases should use REQUIRED. If you think you need REQUIRES_NEW, you probably need NESTED instead.

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

@Service
public class PropagationDemo {

    @Transactional(propagation = Propagation.REQUIRED)
    public void outerMethod() {
        // Transaction T1 starts
        innerMethod(); // Joins T1
        // If innerMethod fails, T1 rolls back completely
    }

    @Transactional(propagation = Propagation.REQUIRED)
    public void innerMethod() {
        // Joins T1
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void independentMethod() {
        // Suspends T1, creates T2
        // T2 commits independently
    }

    @Transactional(propagation = Propagation.NESTED)
    public void nestedMethod() {
        // Creates savepoint in T1
        // On rollback, only savepoint is rolled back
    }
}

4. Isolation Levels and Locking

Isolation levels control how transactions interact with each other. Spring supports five levels: DEFAULT, READ_UNCOMMITTED, READ_COMMITTED, REPEATABLE_READ, and SERIALIZABLE. DEFAULT uses the database's default (usually READ_COMMITTED for PostgreSQL, REPEATABLE_READ for MySQL InnoDB).

Here's the hard truth: most teams get this wrong because they don't understand the trade-offs. READ_UNCOMMITTED allows dirty reads, but improves concurrency. SERIALIZABLE prevents all anomalies but kills performance.

In a payment system, you must use at least READ_COMMITTED to avoid dirty reads. But READ_COMMITTED doesn't prevent non-repeatable reads or phantom reads. For financial transactions, REPEATABLE_READ is often the minimum.

I've seen this blow up in production when a team used READ_COMMITTED for a balance check. Two concurrent transactions read the balance as $100, each deducted $50, and both committed. The final balance was $50 instead of $0. This is a classic lost update anomaly. The fix was to use SELECT ... FOR UPDATE (pessimistic locking) or REPEATABLE_READ with optimistic locking.

Stop doing this: relying on default isolation levels without testing under concurrency. Use pessimistic locking for critical resources, and always test with concurrent load.

Here's an example of pessimistic locking in Spring Data JPA:

``java @Lock(LockModeType.PESSIMISTIC_WRITE) @Query("SELECT a FROM Account a WHERE a.id = :id") Optional findByIdWithLock(@Param("id") Long id); ``

This acquires a database-level write lock, preventing other transactions from reading or writing until the lock is released.

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Isolation;
import org.springframework.transaction.annotation.Transactional;

@Service
public class AccountService {

    @Transactional(isolation = Isolation.REPEATABLE_READ)
    public void transfer(Long fromId, Long toId, BigDecimal amount) {
        Account from = accountRepository.findByIdWithLock(fromId);
        Account to = accountRepository.findByIdWithLock(toId);
        
        if (from.getBalance().compareTo(amount) < 0) {
            throw new InsufficientFundsException("Insufficient balance");
        }
        
        from.setBalance(from.getBalance().subtract(amount));
        to.setBalance(to.getBalance().add(amount));
        
        accountRepository.save(from);
        accountRepository.save(to);
    }
}

// Repository
public interface AccountRepository extends JpaRepository<Account, Long> {
    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @Query("SELECT a FROM Account a WHERE a.id = :id")
    Optional<Account> findByIdWithLock(@Param("id") Long id);
}

5. Rollback Rules and Exception Handling

By default, Spring rolls back transactions for unchecked exceptions (RuntimeException and Error) but not for checked exceptions. This is a common source of bugs. I've seen this blow up in production when a team used a checked BusinessException and expected automatic rollback. The transaction committed partial changes, and data was corrupted.

You must explicitly configure rollbackFor and noRollbackFor:

``java @Transactional(rollbackFor = {BusinessException.class, DataAccessException.class}, noRollbackFor = {OptimisticLockException.class}) public void processOrder(Order order) { // Business logic } ``

Another trap: catching exceptions inside a transactional method. If you catch an exception and don't rethrow it, the transaction will commit even if something went wrong. The correct pattern is:

1. Don't catch exceptions unless you intend to handle the rollback programmatically.
2. If you must catch, use TransactionAspectSupport.currentTransactionStatus().setRollbackOnly() to mark the transaction for rollback.
3. Or rethrow the original exception.

Here's a production pattern I use:

``java @Transactional(rollbackFor = Exception.class) public void processPayment(Payment payment) { try { // Payment logic } catch (Exception e) { // Log the error log.error("Payment failed", e); // Mark transaction for rollback TransactionAspectSupport.currentTransactionStatus().setRollbackOnly(); // Optionally rethrow throw e; } } ``

Stop doing this: catching exceptions in transactional methods without marking for rollback. It's a silent data corruption waiting to happen.

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.transaction.interceptor.TransactionAspectSupport;

@Service
public class PaymentService {

    @Transactional(rollbackFor = PaymentException.class)
    public void processPayment(Payment payment) {
        try {
            // Simulate payment processing
            if (payment.getAmount().compareTo(BigDecimal.ZERO) <= 0) {
                throw new PaymentException("Invalid amount");
            }
            paymentRepository.save(payment);
        } catch (PaymentException e) {
            // Log and mark rollback
            log.error("Payment failed: {}", e.getMessage());
            TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();
            throw e; // Rethrow to propagate
        }
    }
}

class PaymentException extends Exception {
    public PaymentException(String message) {
        super(message);
    }
}

6. Testing Transactions: The Forgotten Art

Testing transactional behavior is notoriously tricky. Most teams write unit tests that don't actually test transaction boundaries. Here's the truth: if you're not testing with a real database and concurrent transactions, you're not testing transactions.

Spring provides @Transactional on test classes, which rolls back after each test. But this masks the real behavior because the test itself is wrapped in a transaction. To test rollback behavior, you need to commit and verify the database state.

Here's my production-tested approach:

1. Use @SpringBootTest with a real database (H2 for unit tests, PostgreSQL for integration tests).
2. Use @Commit on test methods that need to verify committed state.
3. Use CountDownLatch and ExecutorService to simulate concurrent access.
4. Assert database state after the test.

I've seen this blow up in production when a team's test suite passed because @Transactional rolled back, but the actual production code had a bug that caused partial commits. The fix was to add integration tests that actually commit and verify results.

Here's an example of a concurrent test:

``java @Test @Commit public void testConcurrentTransfer() throws InterruptedException { int threadCount = 10; CountDownLatch latch = new CountDownLatch(threadCount); ExecutorService executor = Executors.newFixedThreadPool(threadCount); for (int i = 0; i < threadCount; i++) { executor.submit(() -> { try { accountService.transfer(1L, 2L, BigDecimal.TEN); } finally { latch.countDown(); } }); } latch.await(); // Assert final balances Account from = accountRepository.findById(1L).get(); Account to = accountRepository.findById(2L).get(); assertEquals(BigDecimal.valueOf(0), from.getBalance()); assertEquals(BigDecimal.valueOf(200), to.getBalance()); } ``

Let me be blunt: if you're not writing concurrent transaction tests, you're flying blind.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.annotation.Commit;
import org.springframework.transaction.annotation.Transactional;

import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

import static org.junit.jupiter.api.Assertions.assertEquals;

@SpringBootTest
@Transactional // Rolls back after each test by default
public class TransactionTest {

    @Autowired
    private AccountService accountService;

    @Autowired
    private AccountRepository accountRepository;

    @Test
    @Commit // Override to commit changes
    public void testConcurrentTransfers() throws InterruptedException {
        int threadCount = 10;
        CountDownLatch latch = new CountDownLatch(threadCount);
        ExecutorService executor = Executors.newFixedThreadPool(threadCount);

        for (int i = 0; i < threadCount; i++) {
            executor.submit(() -> {
                try {
                    accountService.transfer(1L, 2L, BigDecimal.TEN);
                } catch (Exception e) {
                    // Expected for some threads
                } finally {
                    latch.countDown();
                }
            });
        }

        latch.await();
        Account from = accountRepository.findById(1L).get();
        Account to = accountRepository.findById(2L).get();
        assertEquals(BigDecimal.valueOf(0), from.getBalance());
        assertEquals(BigDecimal.valueOf(200), to.getBalance());
    }
}

7. Transaction Management with Spring Security

When you combine transactions with Spring Security 6.x, you enter a minefield. The most common issue is the LazyInitializationException when accessing lazy-loaded entities outside a transaction. Spring Security's UserDetails often references entities, and if those entities are loaded lazily, you'll get an error.

I've seen this blow up in production when a controller method returned a user entity, and the view layer tried to access a lazy collection. The transaction had already committed, so Hibernate threw LazyInitializationException. The fix was to use @Transactional on the controller method or use OpenEntityManagerInViewFilter (OEIVF).

But here's the trap: OEIVF keeps the persistence context open for the entire request, which can cause performance issues and LazyInitializationException in async threads. In Spring Boot 3.2+, OEIVF is disabled by default. If you enable it, be aware of the consequences.

Let me be blunt: if you're using OEIVF, you're doing it wrong. It's a crutch that masks underlying design issues. Instead, use DTOs and fetch the data you need eagerly within the transaction.

Here's a proper pattern:

``java @Service @Transactional(readOnly = true) public class UserService { public UserDTO getUserWithRoles(Long userId) { User user = userRepository.findById(userId) .orElseThrow(() -> new UserNotFoundException(userId)); // Fetch roles eagerly via JOIN FETCH or EntityGraph Set roles = user.getRoles(); // Already fetched return new UserDTO(user.getId(), user.getUsername(), roles); } } ``

For authentication, Spring Security's UserDetailsService should not be transactional. If you must load user data within a transaction, use @Transactional on the service method, not the UserDetailsService implementation.

import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class CustomUserDetailsService implements UserDetailsService {

    @Autowired
    private UserRepository userRepository;

    @Override
    @Transactional(readOnly = true) // Transaction for lazy loading
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        User user = userRepository.findByUsername(username)
            .orElseThrow(() -> new UsernameNotFoundException("User not found"));
        // Lazy collections are loaded within the transaction
        return new CustomUserDetails(user);
    }
}

// Controller
@RestController
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/user/{id}")
    public UserDTO getUser(@PathVariable Long id) {
        // No transaction here; UserService handles it
        return userService.getUserWithRoles(id);
    }
}

8. Advanced Patterns: Sagas and Compensation

In distributed systems, you can't rely on ACID transactions across services. This is where the Saga pattern comes in. Spring doesn't provide built-in saga support, but you can implement it with @Transactional and compensation handlers.

I've seen this blow up in production when a team tried to use distributed JTA transactions across microservices. The result: frequent timeouts, deadlocks, and a system that was impossible to debug. The fix was to switch to a saga pattern with local transactions and compensating actions.

Here's a simple saga implementation:

```java @Service public class OrderSaga {

@Transactional(rollbackFor = Exception.class) public void createOrder(OrderRequest request) { try { // Step 1: Reserve inventory inventoryService.reserve(request.getProductId(), request.getQuantity()); // Step 2: Process payment paymentService.charge(request.getUserId(), request.getAmount()); // Step 3: Create order orderRepository.save(new Order(request)); } catch (Exception e) { // Compensation: undo previous steps compensationService.refund(request.getUserId(), request.getAmount()); compensationService.releaseInventory(request.getProductId(), request.getQuantity()); throw e; } } } ```

But here's the trap: compensation actions must be idempotent. If the compensation fails, you need a retry mechanism. I've seen this blow up in production when a compensation action threw an exception, leaving the system in an inconsistent state. The fix was to use a persistent event log and a retry worker.

Stop doing this: implementing sagas without idempotent compensations. Use a message queue (like RabbitMQ or Kafka) to persist saga events and retry on failure.

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class OrderSaga {

    @Autowired
    private InventoryService inventoryService;

    @Autowired
    private PaymentService paymentService;

    @Autowired
    private OrderRepository orderRepository;

    @Autowired
    private CompensationService compensationService;

    @Transactional(rollbackFor = Exception.class)
    public void createOrder(OrderRequest request) {
        try {
            // Step 1
            inventoryService.reserve(request.getProductId(), request.getQuantity());
            // Step 2
            paymentService.charge(request.getUserId(), request.getAmount());
            // Step 3
            orderRepository.save(new Order(request));
        } catch (Exception e) {
            // Compensations (must be idempotent)
            compensationService.refund(request.getUserId(), request.getAmount());
            compensationService.releaseInventory(request.getProductId(), request.getQuantity());
            throw e;
        }
    }
}

// Compensation service with idempotency keys
@Service
public class CompensationService {

    public void refund(Long userId, BigDecimal amount) {
        // Check if already refunded via idempotency key
        // Then process refund
    }

    public void releaseInventory(Long productId, int quantity) {
        // Check if already released
        // Then release
    }
}