Avoiding the 'Partial Success' Trap with Spring @Transactional

The Danger of the Partial Update

Imagine a service method that handles a user's purchase: it deducts credits from a wallet and then creates an order record. If the credit deduction succeeds but the order creation fails due to a database constraint, you end up with a "partial success." The user has lost their money, but no order exists. This inconsistency is a nightmare to debug and a disaster for data integrity.

The goal is atomicity—the "all or nothing" principle. In Spring, the @Transactional annotation is the primary tool to ensure that a series of database operations are treated as a single unit of work. If any part of the process fails, the entire sequence is rolled back to the original state.

How Spring Manages the Boundary

Spring implements @Transactional using Aspect-Oriented Programming (AOP). When you annotate a method, Spring creates a proxy—a wrapper around your bean. When a call hits that proxy, Spring opens a database connection, starts a transaction, and only commits the changes once the method returns successfully.

Propagation and Isolation

Two key settings dictate how these boundaries behave:

• Propagation: This defines what happens if a transactional method is called by another transactional method. The default, REQUIRED, means the method will join the existing transaction if one exists. REQUIRES_NEW suspends the current transaction and starts a completely independent one, which is useful for logging audit trails that must be saved even if the main business logic fails.
• Isolation: This controls how visible changes are to other concurrent transactions. READ_COMMITTED is a common standard that prevents "dirty reads" (reading data that hasn't been committed yet), ensuring your service doesn't make decisions based on temporary, unverified data.

Worked Example: The Order Workflow

Below is an implementation of a purchase service. Note the use of rollbackFor to ensure that even checked exceptions trigger a rollback, as Spring's default behavior only rolls back for RuntimeException and Error.

@Service
public class PurchaseService {

    private final WalletRepository walletRepo;
    private final OrderRepository orderRepo;

    public PurchaseService(WalletRepository walletRepo, OrderRepository orderRepo) {
        this.walletRepo = walletRepo;
        this.orderRepo = orderRepo;
    }

    // Ensure any Exception (checked or unchecked) triggers a rollback
    @Transactional(rollbackFor = Exception.class)
    public void processPurchase(Long userId, OrderRequest request) throws InsufficientFundsException {
        // Step 1: Deduct funds
        Wallet wallet = walletRepo.findByUserId(userId);
        if (wallet.getBalance() < request.getAmount()) {
            throw new InsufficientFundsException("Balance too low");
        }
        wallet.setBalance(wallet.getBalance() - request.getAmount());
        walletRepo.save(wallet);

        // Step 2: Create order
        // If this fails (e.g., Database timeout), Step 1 is rolled back
        Order order = new Order(userId, request.getItems());
        orderRepo.save(order);
    }
}

The Proxy Pitfall: Self-Invocation

A common engineering mistake is calling a @Transactional method from another method within the same class. Because Spring uses a proxy, the transaction logic only triggers when the call comes from outside the bean.

If methodA() (non-transactional) calls methodB() (transactional) inside the same class, the proxy is bypassed, and methodB() will execute without a transaction. To fix this, move the transactional logic to a separate service or inject the service into itself (though the latter is generally discouraged in favor of better architectural layering).

Trade-offs and Performance

While @Transactional provides safety, it comes with a cost. A transaction holds a database connection open for the entire duration of the method. If your method includes a slow external API call or heavy computation, you risk exhausting your connection pool, leading to application-wide latency.

Best Practice: Keep transactional methods lean. Perform API calls and data preparation before entering the transactional boundary, then call a small, focused service method to perform the database writes.

Verifying the Result

To verify your transaction is working, you can use a simple integration test:

1. Insert a known balance into the database.
2. Call the service method with data that will trigger an exception after the first save operation.
3. Query the database to ensure the balance remains unchanged.
4. Check the logs for TransactionSynchronizationManager or set logging.level.org.springframework.transaction=DEBUG to see the Creating new transaction and Rolling back messages in the console.