@Transactional is Not Enough: A Deep Dive into Spring’s PlatformTransactionManager

We’ve all seen it.

A critical operation fails halfway through, leaving data in a corrupted, inconsistent state. The @Transactional annotation was supposed to be the safety net, but it failed. The problem isn’t the tool.

It’s the blind faith we place in it.

To build truly resilient systems, we can’t just trust the magic. We have to understand the engineering behind it. This isn’t just another guide on how to use an annotation. We will take the machine apart, piece by piece, starting from first principles.

Starting from Scratch

An abstraction is a promise. To trust that promise, we must first understand how it’s made. We’re going to ignore the finished machine for a moment and build the engine ourselves, starting with a standard Gradle-based Spring Boot project.

(Code Block: build.gradle)

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.1'
    id 'io.spring.dependency-management' version '1.1.5'
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    runtimeOnly 'com.h2database:h2'
}

For a data-centric application, defining a clear and robust entity is the first step. Using a standard class with Lombok annotations and a protected constructor is a proven, production-ready approach that aligns with JPA’s design.

(Code Block: Customer.java)

@Entity
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
public class Customer {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    private String email;

    public Customer(String name, String email) {
        this.name = name;
        this.email = email;
    }
}

Now, we enter the engine room. By injecting the PlatformTransactionManager, we explicitly control the boundaries of our unit of work. Every line here is a conscious, architectural decision.

@Service
@RequiredArgsConstructor
public class CustomerService {

    private final CustomerRepository customerRepository;
    private final PlatformTransactionManager transactionManager;

    public void createCustomerWithManualTx(String name, String email) {
        TransactionDefinition def = new DefaultTransactionDefinition();
        TransactionStatus status = transactionManager.getTransaction(def);
        try {
            customerRepository.save(new Customer(name, email));
            transactionManager.commit(status);
        } catch (Exception e) {
            transactionManager.rollback(status);
            throw e;
        }
    }
}

This code is verbose, but it is honest. It reveals the five critical steps that @Transactional performs implicitly: defining rules, beginning, executing, committing, and rolling back.

The Elegant Abstraction: @Transactional as Policy

The code above, with its mixed concerns, is precisely the problem that Aspect-Oriented Programming (AOP) was created to solve. @Transactional is not a shortcut; it is a higher-level policy declaration that delegates the five steps we just performed to a proxy.

(Code Block: Refactored CustomerService with @Transactional)

@Service
@RequiredArgsConstructor
public class CustomerService {

    private final CustomerRepository customerRepository;

    @Transactional
    public void createCustomer(String name, String email) {
        customerRepository.save(new Customer(name, email));
    }
}

When you write @Transactional, you are no longer just casting a spell. You are consciously applying a robust engineering policy to your business logic, with a full understanding of the mechanics it represents.

This is the fundamental difference between simply writing code and designing a resilient system.

Beyond the Annotation

Ultimately, mastering @Transactional is not about memorizing annotations or propagation levels. It’s about a shift in mindset.

It’s about treating your data with the respect it deserves, understanding that every database call is a contract with risk. It’s about seeing beyond the code to the system’s underlying state machine. It’s about making conscious, deliberate decisions that lead to resilient, maintainable, and trustworthy software.

That is the real craft of building great systems.