spring-boot · intermediate

Spring Data JPA and Transactions — Persistence Without Surprises

Start here

Spring Data JPA helps Java services talk to relational databases using:

• Entities — classes mapped to tables
• Repositories — interfaces for save/find/query
• JPA/Hibernate — the engine that generates SQL

You should care because most Spring Boot backends persist data this way, and the bugs are legendary: lazy-loading outside a session, transactions not starting, partial commits, and N+1 queries.

What you will learn

1. Map entities and repositories at a conceptual level.
2. Explain what @Transactional actually does.
3. See proxy self-invocation pitfalls.
4. Handle read-only transactions and rollback rules.
5. Work a complete place-order service example.
6. Avoid LazyInitializationException and N+1.
7. Know when to drop to explicit SQL.

What you should know first

Words you need before we begin

Simple story: bank teller batch

A teller posts two ledger lines as one unit: debit and credit. If the second line fails, both must undo. @Transactional is the tray that says “these steps are one unit,” and the proxy is the supervisor who opens and closes that tray when someone calls the official window—not when the teller whispers to themselves in the back (self-invocation).

The problem without clear transaction boundaries

Service method:

1. Save order.
2. Save order lines.
3. Call payment.
4. Save payment result.

Step-by-step explanation

Step 1 — Model entities carefully

Ids, columns, relationships (@ManyToOne, @OneToMany). Prefer clear aggregate boundaries.

Step 2 — Define repositories

JpaRepository<Order, Long> plus query methods or @Query.

Step 3 — Place @Transactional on service layer

Controllers stay thin. Services own business transactions.

Step 4 — Understand the proxy

External call → proxy starts transaction → method runs → commit/rollback. Self-calls inside the same class bypass the proxy unless you restructure.

Step 5 — Rollback rules

Runtime exceptions roll back by default; checked exceptions may not—configure rollbackFor when needed.

Step 6 — Read-only transactions

@Transactional(readOnly = true) for query paths—hints and connection optimizations; still not an excuse for N+1.

Step 7 — Keep transactions short

Do not hold transactions open during remote HTTP calls. Persist intent, commit, then call external systems with idempotency (often with outbox).

Visual mental model

sequenceDiagram
  participant C as Controller
  participant P as Spring proxy
  participant S as OrderService
  participant R as Repository
  participant DB as Database
  C->>P: placeOrder()
  P->>DB: BEGIN
  P->>S: placeOrder()
  S->>R: save
  R->>DB: SQL
  S-->>P: return
  P->>DB: COMMIT
  P-->>C: result

Learning question: If placeOrder calls this.saveLines() as an internal method marked @Transactional, does a new transaction start?

Caption: Usually no—self-invocation skips the proxy.

Complete worked example: place order

Starting situation

OrderService.placeOrder must create order header and lines atomically, then publish an event after commit.

Decisions

Code shape (illustrative)

@Service
public class OrderService {
  @Transactional
  public OrderId place(OrderCommand cmd) {
    Order order = Order.create(cmd);
    orderRepository.save(order);
    // lines cascade or explicit saves
    outboxRepository.save(OrderPlaced.of(order));
    return order.getId();
  }
}

Failure behavior

• Unique constraint on idempotency key: transaction rolls back; client retries safely.
• Lazy load of lines in controller after TX: LazyInitializationException—map to DTO inside TX or fetch join.

How it works in production

• Connection pools (HikariCP)
• Migration tools (Flyway/Liquibase)
• Metrics: TX duration, rollbacks, pool waits
• p6spy/logging for slow SQL in staging

Failure modes

Trade-offs

Compare with related concepts

Common misunderstandings

1. “@Transactional on private methods works.” Proxies typically need public methods on Spring beans called externally.
2. “Save flushes immediately always.” Flush modes vary; commit flushes.
3. “Read-only means no locks ever.” DB isolation still applies.
4. “JPA eliminates N+1.” It can cause them if misused.
5. “One big transaction is safer.” Long transactions increase contention and failure blast radius.

Check your understanding

1. What does a Spring transaction proxy do?
2. Why might @Transactional appear to do nothing?
3. When do LazyInitializationExceptions appear?
4. Why avoid remote calls inside transactions?
5. What is N+1?

Practice

1. Refactor a service that calls payment inside @Transactional.
2. Write a fetch-join query plan for order+lines.
3. Demonstrate self-invocation bug with a small sketch.
4. Choose isolation level notes for a reporting query (conceptual).
5. List metrics for transaction health in production.

Deeper production notes

Testing transactions

@DataJpaTest and @SpringBootTest with rollback defaults can hide commit issues. Include tests that assert committed state visible to another transaction/entity manager.

Multi-datasource and ChainedTransactionManager

Complex; avoid until necessary. Prefer single primary relational store per service.

Specialist caution

Flush timing, second-level cache, and locking (@Lock) have sharp edges. Treat financial ledgers with extra review beyond default JPA patterns.

Revision summary

• Spring Data JPA maps objects to tables; repositories run queries.
• @Transactional defines atomic boundaries via proxies.
• Keep TX short; avoid lazy traps and N+1.
• Combine with outbox for reliable external side effects.
• Know when raw SQL is clearer.

Glossary

Abbreviations and terminology

• JPA — Jakarta Persistence API
• ORM — Object-Relational Mapping
• AOP — Aspect-Oriented Programming (proxy advice)
• OSIV — Open Session In View
• DTO — Data Transfer Object

What to learn next

1. ACID transactions
2. Outbox and sagas
3. Spring Boot best practices
4. N+1 query problem

Additional teaching scenarios

Scenario A — busy day

Imagine traffic multiplies by ten for a marketing event. Re-read the failure modes section and mark which ones become likely first. Write the first mitigation you would take for each marked item. This exercise turns abstract lists into operational instincts.

Scenario B — partial deploy

Half of your instances run the new version and half run the old version. Which assumptions in this lesson break if the two versions disagree about protocols, message fields, or transaction boundaries? Prefer designs that tolerate mixed versions for at least one deploy window.

Scenario C — explain to a new teammate

In five sentences, teach the core idea of this lesson without acronyms. If you cannot, the mental model is not yet solid—revisit the simple story and worked example until the five sentences feel natural.

Scenario D — metric design

List three metrics and one alert threshold you would ship with this mechanism. Good metrics name the user impact or the resource that runs out, not only that a counter incremented.

Scenario E — deliberate non-goals

Write two problems this lesson's technique should not solve. Explicit non-goals prevent cargo-cult adoption where every service gets the same machinery whether it needs it or not.

Scenario F — capacity napkin math

Estimate requests or messages per second at peak, multiply by payload size, and ask whether your chosen design still holds. Napkin math catches fantasy architectures before they meet production invoices.

Scenario G — ownership checklist

Name the team that owns dashboards, the team that owns code changes, and the team that gets paged. If any is blank, fix ownership before enabling the feature broadly.

Additional teaching scenarios

Scenario A — busy day

Imagine traffic multiplies by ten for a marketing event. Re-read the failure modes section and mark which ones become likely first. Write the first mitigation you would take for each marked item. This exercise turns abstract lists into operational instincts.

Scenario B — partial deploy

Half of your instances run the new version and half run the old version. Which assumptions in this lesson break if the two versions disagree about protocols, message fields, or transaction boundaries? Prefer designs that tolerate mixed versions for at least one deploy window.

Scenario C — explain to a new teammate

In five sentences, teach the core idea of this lesson without acronyms. If you cannot, the mental model is not yet solid—revisit the simple story and worked example until the five sentences feel natural.

Scenario D — metric design

List three metrics and one alert threshold you would ship with this mechanism. Good metrics name the user impact or the resource that runs out, not only that a counter incremented.

Scenario E — deliberate non-goals

Write two problems this lesson's technique should not solve. Explicit non-goals prevent cargo-cult adoption where every service gets the same machinery whether it needs it or not.

FAQ from first-time learners

Q: Should controllers be transactional?
A: Prefer service-layer transactions so web concerns stay separate.

Q: Is Hibernate the same as JPA?
A: Hibernate is a common JPA implementation.

Q: Do I need @Transactional for single save?
A: Repository methods may be transactional themselves; service-level TX still helps multi-step use cases.

Track: Java Backend Engineering

Previous: Spring MVC REST APIs

Next: Spring Security OAuth2 Resource Server (JWT)

Series: Spring Boot Production

1. Spring Core Dependency Injection
2. Spring Bean Lifecycle
3. Spring Boot Startup Lifecycle
4. Spring MVC REST APIs
5. Spring Data JPA and Transactions — Persistence Without Surprises (this guide)
6. Spring Security OAuth2 Resource Server (JWT)
7. Spring Boot Best Practices

All series

By Shubham Jain

All articles · Study paths

Shubham Jain · Learning Lab