Spring Data JPA in Full: Repository Abstraction and JPQL

Kill the misconception first: Spring Data JPA is not a machine that writes SQL for you — it is an object-state management system. What you really have to watch is never the shape of a statement but whether this object is currently under the eye of the persistence context. Once that clicks, nine tenths of JPA's "black magic" collapses into common sense: why the row changed although you wrote no UPDATE, why nothing happened right after save, and why you get no Session the moment the transaction ends.

Six words, one line each (used throughout):

• JPA: the specification (Jakarta Persistence) — annotations and interfaces only, no implementation, exactly like the JDBC spec
• Hibernate: Spring Boot's default implementation, the engine that really generates SQL and runs sessions and caches
• Spring Data JPA: the declarative abstraction on top of JPA: you declare interface methods, proxies supply the implementation
• Persistence context: the register of objects under watch during one watching period, whose lifetime normally coincides with a transaction; EntityManager is its entry point
• First-level cache: not a cache you bolt on — it is the persistence context itself. Inside one transaction, one id costs one statement and one instance
• Dirty checking: field values are snapshotted when the entity loads; at flush each field is compared and only the difference becomes an UPDATE

That ring is the map of this article: transient → managed → detached → removed. The four states are decided by two questions (is the object admitted by the context? does it have an identifier?) and the three transitions are persist / find, merge and remove. The honest probe is entityManager.contains(u) — never guess. Section 4 opens every cell.

After this article you should be able to answer three questions:

• I only wrote u.setNickName("new name"), no save, no UPDATE — why did the database really change?
• When does repository.save(entity) actually send SQL? Why does a non-null id cost an extra SELECT?
• One list request logged 101 statements. Which cure fits that N+1, and why is open-in-view not a cure?

Feel the most fragile combination in the whole article first — fetch strategy × moment of access. Flip the switches and the Hibernate SQL log on the right changes immediately:

The biggest confusion when learning JPA is the clashing names: JPA, Hibernate, Spring Data JPA. They are not three competing products but three layers: specification / implementation / abstraction.

In one line: JPA is the contract, Hibernate is the worker, Spring Data JPA is the secretary. One real call chain is worth memorising now, because every later section dissects one of its segments: a Controller line userService.activate(42L) → Spring Data's dynamic proxy (PartTree parsing or SimpleJpaRepository) → EntityManager.find (implemented by Hibernate's Session) → first-level-cache lookup (a hit returns the same instance, no SQL) → on a miss, borrow a connection from HikariCP and send the select (#28).

• You call an interface method, not an implementation you wrote — section 5 shows where the implementation comes from
• Whether the returned object is managed depends on whether the call ran inside a transaction — section 4 is about state
• Whether SQL is sent is decided by dirty checking and the flush moment, not by whether you wrote save — section 10 covers flush

Three lines of dependency buy the whole stack, no hand-written DAO implementation needed:

The starter really brings four things: spring-data-jpa (the Repository abstraction), hibernate-core (the JPA implementation), spring-orm (the glue plus transaction managers) and HikariCP (the default pool, see #28). Auto-configuration enables @EnableJpaRepositories for you, which is why you never write it — but knowing it exists is what lets you debug "my repository was not picked up".

The star of configuration is ddl-auto — it decides how the framework treats your schema at startup, and it is the hot zone for production incidents:

Take the most common situation: the entity gained a remark field and the table did not. update prints one more line at startup, alter table t_user add column remark varchar(255) — it only ever adds: new columns, indexes and tables are fine, dropping a column, changing a type or renaming something is not, and on a shared database whoever boots first owns the schema. validate fails startup outright (Schema-validation: missing column [remark] in table [t_user]), which stops the drift before traffic arrives; none does nothing, so the error slides to the first runtime statement that uses the column — clean boot, random 500s later; create-drop rebuilds on every start, so the schema is right and the data is gone.

The naming strategy trips people up too: CamelCaseToUnderscoresNamingStrategy (Boot's physical naming strategy) maps the property userName to the column user_name; change the strategy or hit a case-sensitive database and you get "table/column does not exist". One discipline covers it: columns snake_case, properties camelCase, let the naming strategy convert, and pin @Column(name = "...") explicitly when you inherit a legacy schema.

That listing is a conclusion, not an exercise. Generate one yourself instead: does datasource alone boot anything, which extra lines appear the moment JPA is ticked, where do those Hibernate: log lines come from, and why the prod profile must differ?

Entities are the heart of JPA; the annotations on the fields define the mapping. Here is one close to real production shape:

The annotation cheat sheet (the right column is all stuff you learn by falling into it):

• @GeneratedValue strategies: IDENTITY uses the database auto-increment column (typical MySQL), SEQUENCE uses a sequence (Oracle / PostgreSQL — keep allocationSize equal to the sequence increment), AUTO lets the framework choose, TABLE emulates one (essentially never used)
• equals / hashCode on the id only: managed entities mutate as flushes happen, so an entity hashed on business fields disappears from a HashSet forever; treating id == null as "never equal" is the cheapest correct rule
• In a bidirectional association (User.orders ↔ Order.user) one side needs @JsonBackReference, or simply return DTOs — otherwise Jackson reports Infinite recursion and toString() throws StackOverflowError

Quiz one — its damage never raises an error, which is why everybody falls for it:

Back to the ring from the opening. In JPA an object only ever has one of four identities, and the identity decides the behaviour:

There is only one probe: entityManager.contains(u). The context flips the state, not the object — the object has been the same one in your hands the whole time; what changed is whether anybody is keeping the books.

The third row of that table is the one that bites in production — detached. Its full shape is "endpoint returns 200, no UPDATE in the log, the row unchanged", with not one exception anywhere. Watch these six frames and you will know what to ask first when an update "occasionally does nothing" (the fix is merge in Section 10, the symptom is the last row of Section 14):

Run the four states yourself; it beats rereading the table ten times:

The ring diagram at the top gives the panorama; what actually has to stick is which action pushes the object into which box. Click through these five boxes — each states what contains() returns right then, and whether anyone is still bookkeeping your field writes:

Spring Data ships a chain of repository interfaces, each richer than the last:

Why is an interface enough, with no implementation class? At startup Spring Data creates a dynamic proxy for each repository interface (RepositoryFactory behind JdkDynamicAopProxy); the real worker is the built-in SimpleJpaRepository, and any method you add is translated by a name parser or by @Query.

This is Spring Data JPA's most charming feature: the method name itself is the query, parsed by convention.

The derived-keyword cheat sheet (these twelve cover daily work):

Derived methods read left to right. The framework strips the prefix (find / read / query / get / count / exists / delete), then By, and parses the rest as property names separated by And / Or — the class doing that job is PartTree. Names must match entity properties (not column names): findByUname cannot find userName, so the application fails at startup with Failed to create query for method ... No property uname found for type User!. That is the friendliest property of derived queries — the error moves forward, and you cannot ship it.

Two nearby mistakes worth noting: findByDeletedFalse also requires deleted to be a real property; and passing null to findByStatusAndUserNameContaining does not "skip that criterion" — it produces like null and returns nothing. Optional conditions belong to Specification in section 8.

When a method name cannot express the query, write it with @Query. JPQL is entity-oriented: it uses entity and property names, not table and column names:

Projection is the badly underrated move: a list page needs three columns, yet the framework assembles whole entities — snapshot, version field, lazy proxies and all — which is slower and one serialization away from a lazy-loading accident.

JPQL can also splice in values with SpEL. This one sorts by a supplied property while a whitelist keeps it safe:

JPA paging is "parameter injection": pass a Pageable as a method argument.

Return a Page<User> as-is and the JSON shape is: content (the page array) plus totalElements, totalPages, number (zero-based), size, first, last. In production wrap it in your own DTO — returning entities exposes version, lazy proxies and the pageable metadata, and usually triggers LazyInitializationException on the way out.

The Page vs Slice difference deserves its own callout:

Once conditions multiply (any of them possibly empty), derived names stop working. The proper JPA answer is Specification — a wrapper over the Criteria API, with QueryDSL as the alternative dialect:

The first thing to know about associations is that the defaults are asymmetric:

So the house style is: make @ManyToOne explicitly LAZY, keep @OneToMany lazy and say so, and let the query — not the entity — decide how much to read.

Now the classic N+1 problem. You want 100 orders with the user who placed each:

Three cures, ordered by scope of change:

• The root cause is "lazy loading + access in a loop": every uninitialised association is a database hit. The only way to locate it is to count statements — show-sql, logging.level.org.hibernate.SQL=debug, or hibernate.generate_statistics: true
• Do not overuse FETCH JOIN on one-to-many: fetching items and user in the same graph multiplies rows (100 orders × 5 items = 500 objects), which is slower than N+1, not faster. A common compromise is one JOIN FETCH o.user plus @BatchSize(size = 50) on the collection
• Cascade and orphanRemoval decide who is saved and deleted with whom; they decide nothing about fetching. Keep the two questions apart

Run the scene in the kernel lab and watch the statement count collapse from 101 back to 1:

That "there is only one way to locate it: count the statements" line deserves its own experiment. On "how to spot it" you see what show-sql and generate_statistics each put in front of you; on "join fetch" and "batching" you watch 101 collapse to different numbers — and this is also where the nastiest trap appears, fetching two collections at once and meeting MultipleBagFetchException:

To really see how "101" grows one statement at a time, spread it out as a single-step run. The six lines on the left are ordinary code from your own project; the right panel updates the variables. Watch sqlCount climb from 1 to 101, and watch the object in step 2 that is not null but a proxy:

Quiz two — this one happens in production logs every single day:

Now connect section 4's state machine with checkout. The truth about save: it persists an object without an id and merges one that has an id, and both only hand the object to the context — neither means SQL.

Those few famous lines inside SimpleJpaRepository are just this branch:

The timing table — memorise it and you never have to guess write behaviour again:

That table is worth compressing into one picture: everything in the left column happens only inside your memory, while only the right column means the database received a statement. Nine tenths of beginner confusion ("why did nothing change", "why is there an extra SELECT") lands on one of these two boxes:

See these two parameters run and "save is not persistence" plus "why detached updates vanish" become things you watched happen:

This question is the interview classic and the production incident at the same time:

Batching is the other face of flushing: Hibernate does not batch automatically. The standard shape is em.flush(); em.clear(); every 50 items — flush lets the batch actually go out (with hibernate.jdbc.batch_size: 50), clear empties the context, otherwise a million entities sit in the heap and memory hurts before the database does.

That "with hibernate.jdbc.batch_size: 50" clause is the only number in this article you can literally drag, and the counter-intuitive part is its default: 0, meaning no batching at all. You assume the framework is collecting statements; it is firing one per row. Drag it and see when it actually buys anything:

JPA decides when SQL goes out; the transaction decides whether the changes count at all; caching answers whether this data can be reused across requests.

save succeeded and the SQL went out, yet if the outer transaction rolls back, the database keeps nothing. Conversely, putting audit logs in a new transaction gives you the deliberate "the business failed but the log survived".

Section 4's identity guarantee lives inside one transaction only. Reusing data across requests is the job of @Cacheable and Hibernate's second-level cache, which people constantly confuse — section 12 puts them in one table.

spring.jpa.open-in-view is one of the few defaults in Boot that bites you, and Boot even logs a WARN telling you to switch it off. What it does is simple: it stretches the persistence context from "the transaction" to "the whole HTTP request" — the EntityManager opens when the request arrives and closes after the view/serialisation is done.

With it off, there are exactly three correct answers, all already introduced: read the needed fields inside the transaction, declare the fetch per method (@EntityGraph / JOIN FETCH), project into DTOs. The third has a bonus: pure data is trivially cacheable.

The context binds to the transaction and the transaction binds to a connection, so open-in-view, long transactions and slow queries all end up reporting themselves as connection-pool metrics. Switch to "Queue at the limit" and "Wait timeout" and match the active / idle / awaiting numbers in SQLTransientConnectionException against the table above:

Caching has to be split into clearly separate layers (four rows below — the query cache is only an appendage of the second level), otherwise "I added @Cacheable and it is still slow" stays unsolvable:

Enough labs — type the same things yourself. This console is wired to the same in-browser kernel and every reply is computed there: query walks Repository → JdbcTemplate once, beans and cond show how this bean got wired in the first place, and then the four themes of this article in order — the four states, the flush moment, N+1, and a pool being slowly drained:

Audit fields (created time / modifier) need no manual assignment: once auditing is on, the framework fills them during the entity lifecycle.

Optimistic locking prevents concurrent overwrites. Add a @Version field and Hibernate carries the version condition into every update:

A concurrent-update failure looks exactly like this:

Where conflicts really are frequent, use a pessimistic lock — it takes the row lock, SELECT ... FOR UPDATE:

Quiz three — what you do after the conflict:

The no Session in the first row is the message that frightens JPA newcomers most, because it reads like "the database connection disappeared" — and it has nothing to do with connections. Here is a real stack: do not read the analysis, just click the frame you think is guilty:

Goal: get User/Dept running and watch the statement count change with the fetch strategy. Dept has just a name field; User.dept is @ManyToOne(fetch = LAZY). UserRepository extends both JpaRepository<User, Long> and JpaSpecificationExecutor<User>, and declares four queries: the derived findByStatusAndUserNameContaining, the paged Page<User> findByStatus(UserStatus, Pageable), the declared-fetch findWithDept (@EntityGraph(attributePaths = "dept")) and the three-column projection findSummaries from section 7. Plus one test:

Expected console output (with show-sql: true the shape must match):

1. Set open-in-view: false and read user.getDept().getName() in the Controller → you get the exact LazyInitializationException from row one of section 14. The most valuable experiment here: the error is not the disaster, it moves the landmine from the end of the request back into the service.
2. Change @ManyToOne(fetch = LAZY) to EAGER → 101 statements become 1, and now every statistic that only wanted an order number JOINs the user table too. Feel a local optimisation turning into a global tax.
3. Call setVersion(3) by hand before saving → watch the version behave differently from what you expected (section 13).
4. Change PageRequest.of(0, 10) to of(1, 10) → the first page disappears; UI page 1 is index 0.
5. Call setXxx inside a @Transactional(readOnly = true) method → clean commit, no UPDATE in the log, database unchanged. The bugs that never error are the hardest to find.
6. Set ddl-auto: update, add a field to the entity and restart → alter table ... add column appears. Switch back to validate and write the migration script instead.

Build GET /admin/orders?keyword=&status=&deptId=&from=&to=&page=1&size=20&sortField=createdAt&order=desc. Acceptance list:

• [ ] Order.user explicitly LAZY; equals/hashCode on id only; @Version present and untouched by business code
• [ ] Dynamic criteria via Specification; when a parameter is absent its condition must not appear in the SQL (no :x is null or ... tricks)
• [ ] The sort field passes a server-side whitelist (entity property names), illegal values fall back to createdAt
• [ ] Ship both a Slice version (no count) and a Page version (with count); paste the two SQL logs in the README and explain why feeds take Slice
• [ ] The list output is a projected DTO; serialising it produces neither per-id top-ups nor LazyInitializationException
• [ ] PATCH /admin/orders/status bulk update with @Modifying(clearAutomatically = true) + @Transactional; explain why that UPDATE does not bump version and how you handle it
• [ ] Load-test 100 concurrent callers while watching hikaricp.connections.pending and the SQL log; decide whether the bottleneck is statement count, mapping overhead or the pool, in five lines

Finish all three tiers and your grasp of JPA moves from "I can write the annotations" to "I know who decided to send each statement, and which layer to debug when it goes wrong".