Spring Data JPA

JPA (Jakarta Persistence API) is a Java specification for ORM and relational persistence.

A Spring project that simplifies data access on top of JPA providers (e.g., Hibernate).

No, it is a specification; implementations include Hibernate, EclipseLink, etc.

Reduces boilerplate repository/CRUD code and standardizes data access patterns.

A lightweight persistent domain object mapped to a database table.

@Entity.

Customizes table mapping details (name, schema, indexes, etc.).

Unique identifier field marked with @Id.

Specifies strategy for automatic primary key generation.

AUTO, IDENTITY, SEQUENCE, TABLE.

Interface-based abstraction for persistence operations.

Provides basic CRUD methods.

Extends paging/sorting + JPA-specific operations.

JpaRepository adds flushing, batch-related helpers, and richer APIs.

Adds pagination and sorting operations.

Query inferred from method name (e.g., findByEmail).

Optional<User> findByEmail(String email);

Select rows matching property criteria encoded in method name.

Checks existence without fetching full entity.

Returns count of matching rows.

Container representing possible absence of entity.

Defines custom JPQL/native query on repository method.

JPQL queries entities/fields; SQL queries tables/columns.

Treats @Query string as database-native SQL.

Binds named method parameter to query parameter.

Defines transaction boundaries for persistence operations.

Many are transactional by default (read-only for reads, write for mutations), depending on configuration.

Core JPA interface for persistence context operations.

First-level cache and tracking context for managed entities.

Transient, Managed, Detached, Removed.

New object not associated with persistence context.

Tracked by persistence context; changes may be synchronized automatically.

Previously managed but no longer attached to current persistence context.

Marked for deletion in current transaction.

Automatic detection of managed entity changes and SQL update generation.

Synchronizing persistence context changes to database.

Flush sends SQL; commit finalizes transaction permanently.

Persists new entity or merges existing depending on identifier state/provider behavior.

Deletes entity by primary key.

Fetches all records (use carefully on large tables).

Memory/performance issues on large datasets.

Fetching data in chunks/pages rather than all at once.

Spring Data abstraction for page request (page, size, sort).

Result containing content plus total counts and page metadata.

Page-like result without total count query.

When total count is expensive/unnecessary.

Abstraction for ordering query results.

Customizes column mapping properties.

Column cannot store NULL values.

Requests unique constraint (DDL generation context).

Controls enum persistence strategy (ORDINAL or STRING).

Safer against enum order changes.

Maps large object fields (BLOB/CLOB).

Specifies temporal precision for old Date/Calendar mappings.

Use java.time types (LocalDate, Instant, etc.) with provider support.

Exposing entities directly in external API contracts.

Prevents coupling and accidental lazy loading/leaks.

One query for parent list + many queries for child data per row.

Use fetch joins/entity graphs strategically.

Model entities clearly, paginate reads, and understand transaction boundaries.

Associating entities via one-to-one, one-to-many, many-to-one, many-to-many.

Maps one entity instance to one related instance.

Maps parent to multiple child entities.

Maps many child rows to one parent.

Maps many-to-many association, often via join table.

Indicates inverse side of bidirectional association.

Owning side controls foreign key/join table updates.

Association loaded on access (provider may use proxies).

Association loaded immediately with entity (can hurt performance).

Can cause over-fetching, N+1 variants, and heavy queries.

Propagating persistence operations from parent to associated entities.

PERSIST, MERGE, REMOVE, REFRESH, DETACH, ALL.

Deletes child row when removed from parent collection/association.

REMOVE propagates parent delete; orphanRemoval handles disassociation cleanup.

Defines foreign key column mapping.

Defines association join table details.

Inconsistent both-side updates causing stale object graph state.

Utility methods updating both sides consistently.

Value object type embedded in entity table columns.

Embeds @Embeddable object into entity.

Overrides embedded field column mapping names.

Base class contributing mappings to subclasses, not its own table.

Mapping class hierarchies to relational structures.

SINGLE_TABLE, JOINED, TABLE_PERCLASS.

Fast reads/simple joins; nullable unused columns and weaker normalization.

Normalized schema; extra joins for polymorphic queries.

Independent tables; union-heavy polymorphic queries can be expensive.

Column distinguishing subclass type in SINGLE_TABLE.

Version-based concurrency control detecting conflicting updates.

@Version.

Exception (e.g., OptimisticLockException) and transaction rollback.

Database lock acquisition during transaction to prevent concurrent modifications.

Use @Lock with lock mode on repository query methods.

More blocking/deadlock risk but stronger immediate consistency control.

Join that eagerly fetches association in single query.

Can produce duplicates/incorrect paging depending on relationship cardinality/provider behavior.

Declarative fetch plan for specific query use cases.

Control loading without hardcoding eager mappings globally.

Query returns non-entity shape mapped to interface/class DTO.

Interface-based, class-based (constructor), open projections.

Reduce selected columns and serialization overhead.

Projection exposing mapped fields only.

May use SpEL/computed values with potential performance overhead.

Marks repository query as update/delete operation.

Write queries need transaction boundary.

Clears persistence context after bulk update to avoid stale managed entities.

Bypasses dirty checking for existing managed instances.

Persistence context cache scoped to EntityManager/transaction.

Shared cache across sessions/entity managers (provider-specific, optional).

Query cache stores result ids/sets; entity cache stores entity state.

Loading multiple lazy associations/entities in grouped queries.

Grouping SQL writes to reduce round trips.

Immediate key retrieval requirements can reduce batch efficiency.

Controls when persistence context flush occurs (AUTO/COMMIT variants).

Hints provider/DB for read paths, potentially reducing overhead.

Criteria-based composable query predicates.

Dynamic filtering with reusable predicate components.

Type-safe programmatic query construction API in JPA.

Very long names become unreadable and hard to maintain.

When query complexity grows beyond clarity.

Automatic population of created/modified timestamps/users.

@CreatedDate, @LastModifiedDate, @CreatedBy, @LastModifiedBy.

Configuration with @EnableJpaAuditing and auditor provider.

Mark records deleted via flag/timestamp instead of physical delete.

Need global filters and uniqueness/index strategy consideration.

Open session plus lazy serialization causing unexpected DB queries in web layer.

Fetch explicitly in service layer and map to DTOs within transaction.

@DataJpaTest for repository slice plus integration tests for complex queries.

H2 behavior may differ from production DB features/plans.

Design fetch plans per use case and validate with SQL logs/profiling.

Small query/mapping changes can trigger inefficient DB execution plans.

Track SQL counts, latency percentiles, and execution plans in CI/perf tests.

Joining multiple collections can multiply row counts drastically.

Split queries, projection strategy, dedicated read models.

Cursor-based paging using stable sort key for large datasets.

Better performance and consistency for deep pages.

Custom queries/repositories beyond basic Pageable offset style.

Isolating tenant data via schema/database/discriminator strategies.

Leaky filters, wrong cache keys, cross-tenant query exposure.

Store domain event and entity changes atomically in same DB transaction.

Reliable event publishing without distributed transactions.

Publishing before commit can leak rolled-back state.

Publish after commit or process outbox asynchronously.

Context spans multiple transactions (less common in typical Spring Boot apps).

Memory growth, stale data, unintended flush side effects.

Blind merge may overwrite newer DB state unintentionally.

Load managed entity then apply explicit field changes.

Concurrent transactions read overlapping data and write disjoint rows violating invariant.

Not for all invariants; sometimes need stronger isolation or explicit locks.

Retry idempotent transactions with backoff on transient deadlock errors.

Differentiate retryable transient vs fatal integrity/configuration failures.

Repositories per aggregate root with invariant-preserving operations.

They leak persistence concerns and weaken aggregate boundaries.

Use dedicated projections/queries for reads, separate from write model complexity.

Batch size, flush/clear cycles, sequence strategy, JDBC settings.

Prevents persistence context memory bloat.

Keeping cached entity state consistent across updates/nodes.

Highly volatile data with low hit ratio.

Caching highly dynamic query results can create stale/memory-heavy behavior.

Marking reference data immutable can reduce dirty checking/update overhead.

Alternative business-key identity mapping for lookups/caching.

Need refresh/reload strategies to observe computed/default values reliably.

Store STRING values and plan rename migrations explicitly.

Map structured fields to JSON columns with converter/provider support.

JPA mechanism converting between entity attribute type and DB column type.

Encryption wrappers, value objects, custom serialization.

Can hide queryability/indexing implications of transformed values.

Transaction/read consistency issues under replication lag.

Route critical follow-up reads to primary or enforce consistency window.

SQL timing, slow query logs, pool metrics, lock wait/deadlock metrics, error taxonomy.

Early indicator of contention and transaction design issues.

Backward-compatible phased DB/app changes across rolling deploys.

Add new schema first, dual-read/write if needed, then remove old schema later.

Unit (minimal), repository slice, integration with real DB, migration tests, performance tests.

Prevent drift between entity mappings and schema migration history.

Ignoring generated SQL and assuming ORM always produces efficient queries.

Review SQL plans, tune mappings intentionally, and measure continuously.

For critical paths needing handcrafted SQL or specialized data access patterns.

Model aggregates clearly and align persistence operations with business invariants.

Use Spring Data JPA for productivity, but validate every performance and consistency assumption.