JPA, Hibernate, transactions and locking
Spring Data JPA makes database code look trivially easy, which is exactly why interviewers dig into it. This module explains what really happens: the persistence context, dirty checking, flushes, lazy loading and N+1, how repositories work, every important @Transactional setting, and how Arena combines optimistic and pessimistic locking. It also covers when Arena deliberately drops down to plain SQL.
By the end you can answer
- "What is the persistence context? What is dirty checking?"
- "Why does
MatchServicenever callsave()on the players it changes?" - "What is the N+1 problem and how do you fix it?"
- "What does
LazyInitializationExceptionmean? What is open-in-view?" - "Explain transaction propagation, especially
REQUIRES_NEW. What doesreadOnlydo?" - "Why
TransactionTemplateinstead of@TransactionalinrecordMatch?" - "How does
@Versionwork, and when would you lock pessimistically?"
1. JPA, Hibernate and Spring Data: who does what
| Layer | What it is | In Arena |
|---|---|---|
| JDBC | Java's low-level API for sending SQL and reading result sets | Underneath everything; JdbcClient is a thin, modern wrapper used for raw SQL |
| JPA (Jakarta Persistence) | A specification: annotations (@Entity), EntityManager, JPQL | The jakarta.persistence.* imports |
| Hibernate | The most popular JPA implementation (the ORM engine) | Chosen automatically by Spring Boot |
| Spring Data JPA | Generates repository implementations from interfaces | PlayerRepository extends JpaRepository<Player, UUID> |
An ORM (object-relational mapper) bridges the "impedance mismatch" between objects (references, inheritance, graphs) and tables (rows, foreign keys, joins). It saves a lot of boilerplate for writes and simple reads, and it hides costs you must understand.
2. Mapping entities
@Entity
@Table(name = "players")
@Getter @Setter
@NoArgsConstructor(access = AccessLevel.PROTECTED) // JPA needs a no-arg constructor; nobody else should use it
public class Player {
@Id
private UUID id; // assigned in Java (UUID.randomUUID())
@Column(nullable = false, length = 20)
private String username;
@Enumerated(EnumType.STRING) // store "BANNED", not 3
@Column(nullable = false, length = 16)
private AccountStatus status;
@JdbcTypeCode(SqlTypes.CHAR) // column is CHAR(2), not VARCHAR
@Column(length = 2)
private String country;
@Version
@Column(nullable = false)
private Long version; // optimistic locking (section 9)
...
}
EnumType.STRING, neverORDINAL. Ordinal stores the position (0, 1, 2...). Insert a new constant in the middle of the enum and every existing row silently changes meaning.- The no-arg constructor is required because Hibernate creates instances by reflection, and creates proxies (subclasses) for lazy loading. Making it
protectedstops application code from creating half-built entities. ddl-auto: validatechecks these mappings against Flyway's tables at startup, which is why@JdbcTypeCode(SqlTypes.CHAR)is needed forcountry: otherwise Hibernate expectsVARCHARand validation fails.
Relationships
@ManyToOne(fetch = FetchType.LAZY, optional = false)
@JoinColumn(name = "player_id", nullable = false)
private Player player;
@ManyToOne defaults to EAGER in JPA, which is a common performance trap. Arena sets LAZY explicitly: the field holds a proxy, and the player row is loaded only when you touch it.
Composite keys: MatchParticipant uses @EmbeddedId MatchParticipantId (match id + player id) with @MapsId("matchId") and @MapsId("playerId") on its two @ManyToOne fields. The key is derived from the relationships, mirroring the SQL primary key (match_id, player_id).
Why Lombok @Data is banned on entities
@EqualsAndHashCodeover all fields: the hash changes when a field changes, breaking anyHashSetthe entity is in, and compares lazy proxies field by field.@ToString: touches lazy associations (triggering queries orLazyInitializationException) and can recurse forever between two entities that reference each other.- Safe default: don't override
equals/hashCodeon entities (identity semantics), or base them on an immutable business key or the assigned id, carefully.
3. The persistence context and dirty checking
This is the most important idea in JPA. Inside a transaction, Hibernate keeps a persistence context (also called the first-level cache or the unit of work): a map from (entity type, id) to the managed object, plus a snapshot of each object's state when it was loaded.
transaction begins
findAllByIdInForUpdate(ids) ─► SELECT ... FOR UPDATE ─► Player objects become MANAGED
(snapshots kept)
player.setRating(1030) ← just a Java setter; no SQL yet
player.setMatchesPlayed(...)
commit
flush: compare each managed entity with its snapshot ("dirty checking")
─► UPDATE players SET rating=?, matches_played=?, ..., version=version+1
WHERE id=? AND version=?
COMMIT
That's why MatchService and ModerationService never call playerRepository.save(player) after changing a player: the entity is managed, and every change is written automatically at flush. Calling save() on a managed entity is harmless but pointless.
Entity states
| State | Meaning |
|---|---|
| Transient (new) | Just created with new; Hibernate doesn't know it |
| Managed | Loaded or persisted in the current persistence context; changes are tracked |
| Detached | Was managed, but the context closed (the transaction ended); changes are no longer tracked |
| Removed | Scheduled for deletion at flush |
When does a flush happen?
- Before commit.
- Before a query whose result could be affected by pending changes (Hibernate's default AUTO flush mode).
- When you call
flush()orsaveAndFlush(). Arena usesmatchRepository.saveAndFlush(match)to send the INSERT immediately, so a duplicateexternalIdfails right there inside the transaction instead of later at commit, and the match row exists before participants reference it.
The persistence context also guarantees one object per row within a transaction: loading the same player twice returns the same Java instance, without a second SELECT.
save() means persist or merge
SimpleJpaRepository.save(entity) asks "is this entity new?". If yes it calls persist (one INSERT at flush); if no it calls merge, which first SELECTs the row to copy state onto a managed instance. How does it decide? If the entity has a non-primitive @Version field, "new" means "version is null"; otherwise it means "id is null".
Arena assigns UUIDs in Java, so ids are never null. Player and Appeal have a @Version Long that is null until first saved, so they take the efficient persist path. Match, MatchParticipant, ModerationAction and RefreshToken have no @Version, so save() treats them as existing and calls merge, which costs an extra SELECT before each INSERT. MatchParticipant matters most: its id is an @EmbeddedId built from the match and player ids (also never null), and saveAll merges every participant, so recording a match makes one extra SELECT per player. (merge also returns a different, managed instance, which is why you should use the return value of save().) The fix, if it mattered, is to implement Persistable<UUID> (Persistable<MatchParticipantId> for the participant) with an isNew() flag or add a nullable @Version. You can see the behaviour yourself with logging.level.org.hibernate.SQL=debug. Knowing this, and how you'd check it, is a strong senior-level signal.
A follow-up an interviewer who reads your code could ask: MatchService calls matchRepository.saveAndFlush(match) and ignores the returned instance, then keeps using the original match when it builds the participants. Why does that work? When the participants are saved, Hibernate resolves their reference to the match by its id, and finds the managed copy already in the persistence context. It's correct but subtle, so the safer answer is: "I'd use the returned instance, or implement Persistable so save() persists the original object directly. I'd confirm the current behaviour with SQL logging first."
4. Lazy loading, N+1 and open-in-view
The N+1 problem
// Looks innocent:
List<MatchParticipant> ps = repo.findByMatchId(matchId); // 1 query: 10 participants
for (MatchParticipant p : ps) {
p.getPlayer().getUsername(); // each lazy proxy loads: 10 more queries
} // total: 1 + N
With lists of 100 rows, that's 101 round trips. It's the most common ORM performance bug, and invisible in code review unless you know to look. Fixes:
JOIN FETCHin JPQL: load the association in the same query.arena/.../match/MatchParticipantRepository.java
Arena does the same for refresh tokens (@Query(""" select mp from MatchParticipant mp join fetch mp.player where mp.match.id = :matchId order by mp.placement asc """) List<MatchParticipant> findByMatchIdWithPlayerOrderByPlacement(@Param("matchId") UUID matchId);join fetch t.player) and appeals (join fetch a.player left join fetch a.decidedBy).- DTO projections: select exactly the columns you need straight into a record, so no entities and no lazy proxies:
That'sselect new dev.fairplay.arena.match.dto.PlayerMatchResponse( m.id, m.externalId, m.gameMode, m.mapName, m.endedAt, mp.placement, ..., mp.ratingAfter) from MatchParticipant mp join mp.match m where mp.player.id = :playerId order by m.endedAt desc, m.id descfindPlayerMatches, a paged read for "my match history". - Entity graphs (
@EntityGraph) or Hibernate batch fetching (load proxies in groups withIN (...)). - Bulk lookups:
LeaderboardServicetakes the ids from Redis and callsplayerRepository.findAllById(ids)once, then maps by id. One query instead of one per leaderboard row.
LazyInitializationException and open-in-view
Touching a lazy proxy after the transaction (and persistence context) has closed throws LazyInitializationException: there's no session left to load from. Spring Boot's default Open Session in View keeps the persistence context open until the HTTP response is written, so such access "just works", by silently running extra queries during JSON serialisation and holding a database connection for the whole request. Boot even logs a warning about it.
Arena sets spring.jpa.open-in-view: false. Services must load everything they need inside the transaction (with fetch joins or projections) and return DTOs. Mistakes fail loudly in tests instead of becoming slow production queries.
5. Spring Data repositories
You write an interface; Spring generates a proxy implementation at startup. Query methods come in three flavours:
| Style | Example in Arena | Notes |
|---|---|---|
| Inherited CRUD | findById, findAllById, save, saveAll, existsById, getReferenceById | From JpaRepository |
| Derived from the method name | findByExternalId, existsByBanActionId, findFirstByPlayerIdAndActionOrderByCreatedAtDesc | Spring parses the name into JPQL; great for simple filters |
@Query JPQL | findByUsernameIgnoreCase (lower(p.username) = lower(:username)), searchPlayers, findAllByIdInForUpdate | JPQL uses entity and field names, not table and column names |
getReferenceById(id)returns a proxy without a SELECT.MatchServiceuses it for the recorder: it only needs the foreign key forrecorded_by, not the recorder's data.@Modifyingbulk updates:revokeAllActiveForPlayeris anupdate ... whereJPQL statement run directly in the database. It bypasses the persistence context: entities already loaded in memory won't reflect the change unless you clear the context (@Modifying(clearAutomatically = true)). Here it runs in its ownREQUIRES_NEWtransaction, so nothing stale is reused.- Paging: methods taking a
Pageableand returningPage<T>run the data query withLIMIT/OFFSETplus a count query. Supplying an explicit, cheapercountQuery(asfindPlayerMatchesdoes) avoids counting through unnecessary joins.
When Arena skips JPA: JdbcClient
JPA is excellent for loading and changing entities. For analytics and special SQL it gets in the way. Arena uses JdbcClient (named parameters, row mappers, a fluent API) for: the percentile_cont query, the database rank count with COLLATE "C", the moderation queue's JOIN LATERAL, and keyset streaming during the Redis rebuild. Saying "I used the ORM for aggregates I write, and plain SQL for read models and reports" is a sign of maturity.
6. @Transactional in depth
Recap from module 03: Spring wraps the bean in a proxy that begins a transaction, calls your method, then commits or rolls back. Now the settings.
Rollback rules
- By default: roll back on unchecked exceptions (
RuntimeException,Error); commit on checked exceptions. Surprising to many people. Change it withrollbackFor = Exception.class. - Arena's
ApiExceptionis unchecked, so throwing it anywhere in a service method rolls back everything that method did. That's whyAuthService.refreshneeds a separate transaction for the revocation it wants to keep. - If you catch an exception inside the method, the proxy never sees it, so no rollback, unless an inner transactional call already marked the transaction rollback-only, in which case commit fails with
UnexpectedRollbackException.
Propagation: what happens when a transactional method calls another
| Propagation | Behaviour | Use |
|---|---|---|
| REQUIRED (default) | Join the current transaction, or start one | Almost everything |
| REQUIRES_NEW | Suspend the current transaction and run in a brand-new, independent one that commits or rolls back on its own | Arena's refresh-token reuse revocation must commit even though the outer transaction rolls back. Also audit logging of failures |
| NESTED | A savepoint inside the current transaction: an inner rollback doesn't kill the outer one | Partial retries within one unit of work |
| SUPPORTS / NOT_SUPPORTED / MANDATORY / NEVER | Use it if present / suspend it / require it / forbid it | Rare |
While the inner transaction runs, the outer one is suspended but still holds its connection, so REQUIRES_NEW needs two pooled connections at once. With a small pool and many concurrent requests doing this, you can exhaust the pool and deadlock on connections. Arena uses it only on the rare reuse-detection path.
readOnly = true
Arena marks query methods @Transactional(readOnly = true). For Hibernate this means: no dirty-checking snapshots and no flush at the end, so it's faster and uses less memory. The JDBC driver is told the connection is read-only, and routing data sources can use it to send reads to a replica. It documents intent too. It is not a security mechanism.
Programmatic transactions: TransactionTemplate
public RecordResult recordMatch(RecordMatchRequest request, UUID recorderId) {
try {
return recordTx.execute(status -> doRecordMatch(request, recorderId)); // the transaction
} catch (DataIntegrityViolationException ex) { // after rollback
Optional<Match> winner = matchRepository.findByExternalId(request.externalId());
if (winner.isPresent()) {
return new RecordResult(toResponse(winner.get()), false); // 200 replay
}
throw ex;
}
}
Why not just annotate recordMatch with @Transactional and catch inside? Because of how PostgreSQL handles errors: once a statement fails inside a transaction, the whole transaction is aborted, and every further statement fails with "current transaction is aborted, commands ignored until end of transaction block". The replay lookup must run after the rollback, in a fresh transaction. TransactionTemplate makes the boundary an explicit block of code you can wrap in try/catch. It also avoids the proxy self-invocation pitfall, since doRecordMatch is a private method.
Keep transactions short and free of side effects
- A transaction holds a pooled connection, and any row locks, for its whole duration. With 20 connections, slow transactions throttle the whole app.
- Never call slow external systems (HTTP, Kafka, Redis) inside a database transaction: you hold locks while waiting, and the external call can't be rolled back if the database later rolls back. Arena updates Redis
AFTER_COMMIT(module 08) for exactly this reason.
7. Putting it together: one POST /matches transaction
TransactionTemplate.executebegins a transaction and borrows a connection.- Validate the request (cross-field rules).
findByExternalId: already recorded? Return it (200).- Sort the participant UUIDs;
findAllByIdInForUpdaterunsSELECT ... ORDER BY id FOR UPDATE. Rows are locked in a fixed order, entities become managed. - Check all exist (404) and are eligible, not banned or appealed (422).
getReferenceById(recorderId): a proxy, no SELECT.saveAndFlush(match): the INSERT runs now, and the uniqueexternal_idfires here on a race.- For each participant: compute the rating delta with the pure
RatingCalculator, change fields on the managedPlayer(no save), build aMatchParticipant, publishRatingChanged(held until commit). saveAll(participants); increment a Micrometer counter.- Commit: dirty checking flushes N
UPDATE players ... WHERE id=? AND version=?statements; the locks are released; theAFTER_COMMITlisteners push ratings to Redis. - On a unique-violation race: rollback, catch outside, return the winner (200).
8. Optimistic and pessimistic locking in JPA
Optimistic: @Version
Every update Hibernate generates includes the version it read and increments it:
UPDATE players SET display_name = ?, version = 8 WHERE id = ? AND version = 7
If another transaction already bumped the version to 8, this updates 0 rows. Hibernate throws OptimisticLockException, Spring translates it to ObjectOptimisticLockingFailureException, and Arena's GlobalExceptionHandler answers 409 CONCURRENT_MODIFICATION, "please retry". No locks are held while the user or code is thinking; conflicts are detected at write time.
Example: two moderators decide the same appeal simultaneously. Both read it as PENDING with version 3. The first commit sets version 4; the second gets 0 rows and a 409. Without @Version, the second would silently overwrite the first decision.
Pessimistic: @Lock(PESSIMISTIC_WRITE)
Translates to SELECT ... FOR UPDATE: other writers (and other FOR UPDATE readers) wait until you commit. Arena uses it for match recording, where collisions on popular players are expected and retrying a whole 100-player match would be wasteful. The rows are locked in sorted order to make deadlocks impossible (module 06). The @Version still increments on those updates, so other optimistic readers detect the change.
| Optimistic | Pessimistic | |
|---|---|---|
| Mechanism | Version check at write time | Row lock at read time |
| On conflict | Fail fast (409 or retry) | Wait |
| Best when | Conflicts rare; long think-time; user-facing edits | Conflicts likely; retries expensive; short transactions |
| Risks | Retry storms under heavy contention | Lock waits, deadlocks (needs ordering), held connections |
| Arena | Player, Appeal (@Version) | findAllByIdInForUpdate in POST /matches |
9. Interview questions
JPA vs Hibernate vs Spring Data JPA? Basic
JPA is the specification (annotations, EntityManager, JPQL). Hibernate is the implementation that actually generates SQL and manages entities. Spring Data JPA sits on top and generates repository implementations from interfaces: derived queries, @Query, paging. In Arena I also use JdbcClient for plain SQL where an ORM is the wrong tool.
What is dirty checking? Why don't you call save() after changing a player? Intermediate
Entities loaded in a transaction are managed by the persistence context, which keeps a snapshot of their state. At flush (before commit, or before an affected query) Hibernate compares each managed entity with its snapshot and issues UPDATEs for what changed. In MatchService the players are loaded with FOR UPDATE, then I just call setters; the commit writes the changes, including the optimistic version increment.
Explain the N+1 problem and how you avoided it. Intermediate
Loading N rows and then touching a lazy association on each triggers one extra query per row: 1 + N round trips. I avoid it with join fetch where I need entities (participants with players, refresh tokens with their player, appeals with player and decider), with a JPQL constructor projection straight into a DTO for paged match history, and with one findAllById for leaderboard rows instead of a lookup per row. Open-in-view is disabled so accidental lazy loading fails in tests instead of quietly adding queries.
What does open-in-view do and why disable it? Intermediate
It keeps the persistence context (and a database connection) open for the whole web request, so lazy associations can load during view rendering or JSON serialisation. That hides N+1 queries in the presentation layer and holds pooled connections longer, which hurts under load. With it off, services must fetch what they need in the transaction and return DTOs, and mistakes surface as LazyInitializationException in tests.
When does @Transactional roll back? Basic
By default on unchecked exceptions (RuntimeException, Error) that propagate out of the proxied method, and not on checked exceptions unless rollbackFor says so. Exceptions caught inside the method don't trigger rollback, unless an inner transactional call already marked the transaction rollback-only. My business errors are unchecked ApiExceptions, so they roll back automatically.
What is REQUIRES_NEW and where did you need it? Deep
It suspends the current transaction and runs the work in an independent one that commits or rolls back on its own. In refresh-token reuse detection, I revoke all of the player's tokens and then throw REFRESH_TOKEN_REUSED. The exception rolls back the outer transaction, which would undo the revocation, so the revocation runs through a TransactionTemplate configured with PROPAGATION_REQUIRES_NEW and commits first. The caveat: the suspended outer transaction still holds its connection, so REQUIRES_NEW needs two connections; use it sparingly.
Why does recordMatch use TransactionTemplate instead of @Transactional? Deep
When two identical requests race, the loser hits the unique constraint on external_id. In PostgreSQL, any error aborts the transaction, so I can't run the "find the winner" query in it. I need to let it roll back, then query in a fresh transaction and return 200 with the winner's match. TransactionTemplate makes the transaction an explicit block I can wrap in try/catch, catching DataIntegrityViolationException after rollback. With a @Transactional method, the catch would have to sit in a different bean, and self-invocation pitfalls would apply.
How does @Version work and what does the client see on a conflict? Intermediate
Hibernate adds AND version = ? to every UPDATE and increments the version. If another transaction changed the row first, zero rows match, Hibernate throws an optimistic lock exception, and Spring translates it to ObjectOptimisticLockingFailureException. Arena's global handler maps that to 409 CONCURRENT_MODIFICATION, so the client re-reads and retries. It protects against lost updates without holding locks, for example two moderators deciding the same appeal.
What does readOnly = true actually change? Intermediate
Hibernate skips dirty-checking snapshots and doesn't flush, which saves CPU and memory on large reads. The connection is flagged read-only, which a routing data source can use to send the query to a replica. It documents intent. It doesn't stop a determined write from executing on every database, so it's an optimisation and a hint, not a guard.
What's getReferenceById for? Intermediate
It returns a lazy proxy holding only the id, without a SELECT. It's ideal when you only need the entity as a foreign key. MatchService uses it for the recording service account: recorded_by just needs the UUID. If the row doesn't exist, you only find out on first access or at flush via the foreign-key constraint.
Your entities have assigned UUIDs. What does save() do with a brand-new Match? Curveball
Spring Data decides between persist and merge with isNew(): with a non-primitive @Version it checks whether the version is null, otherwise whether the id is null. Match has an assigned id and no @Version, so it looks "not new" and save() calls merge, which SELECTs the row before inserting, an avoidable extra query, and returns a different managed instance. Player and Appeal have a nullable @Version, so they take the persist path. The fix is implementing Persistable or adding a version; I'd confirm with SQL logging before optimising.
A @Modifying update ran, but an entity you loaded earlier still shows the old value. Why? Curveball
Bulk JPQL updates run directly in the database and bypass the persistence context, so already-managed entities keep their in-memory state. Use @Modifying(clearAutomatically = true) (and maybe flushAutomatically), re-query, or run the bulk update in a separate transaction, as Arena's revocation does with REQUIRES_NEW.
Why EnumType.STRING? Basic
ORDINAL stores the enum's position, so inserting or reordering constants silently changes the meaning of existing rows. STRING stores the name, which is readable in SQL, matches the CHECK constraints, and is only affected by renames, which are contract changes anyway.
10. Quick quiz
1. You load a player in a transaction and call setRating(1030). Without save():
Managed entities are tracked automatically.
2. A @Transactional method throws a checked IOException. By default:
The default is rollback on unchecked exceptions only.
3. Which fixes N+1 when loading participants with their players?
Load the association in the same query.
4. An optimistic-lock conflict in Arena becomes:
The handler maps ObjectOptimisticLockingFailureException.
5. After a unique violation inside a PostgreSQL transaction, you can:
Hence the catch outside the TransactionTemplate.
6. REQUIRES_NEW nested inside an outer transaction needs:
Overusing it under load can exhaust the pool.
11. Cheat sheet
- Stack: JDBC < JPA (spec) < Hibernate (impl) < Spring Data (repositories);
JdbcClientfor raw SQL. - Entity:
@Entity, assigned UUID@Id,EnumType.STRING, protected no-arg constructor, explicitLAZYon@ManyToOne,@EmbeddedId+@MapsId,@Version; no@Data. - Persistence context: one object per row; snapshots; dirty checking at flush; states transient / managed / detached / removed.
- Flush: before commit, before affected queries,
saveAndFlush(fail early on a constraint). save()= persist if new, else merge (an extra SELECT). An assigned id without@Versionmeans merge; fix withPersistable.- N+1: join fetch, DTO projection, entity graph or batch fetching,
findAllById. Open-in-view off. - Repositories: derived names,
@QueryJPQL,@Modifying(bypasses the context),Pageable+ countQuery,getReferenceById. @Transactional: proxy; rollback on unchecked; REQUIRED default; REQUIRES_NEW = independent commit, two connections; readOnly = no dirty checking.TransactionTemplate: explicit boundary; catch after rollback (a PostgreSQL error aborts the transaction).- Short transactions, no external calls inside; side effects after commit.
- Locking:
@Version→ 409 on conflict;PESSIMISTIC_WRITE=FOR UPDATE, ordered by id.