jpa-patterns

name	jpa-patterns
description	JPA/Hibernate patterns and common pitfalls (N+1, lazy loading, transactions, queries). Use when user has JPA performance issues, LazyInitializationException, or asks about entity relationships and fetching strategies.

JPA Patterns and Best Practices

Quick Reference - Common Problems

Problem	Symptom	Solution
N+1 Queries	Slow list operations, many SQL queries	JOIN FETCH, @EntityGraph, batch fetching
LazyInitializationException	Error accessing lazy field outside transaction	Fetch in query, DTO projection, Open Session in View
Detached Entity	save() creates duplicate instead of update	Use findById() + modify, or @Transactional
Optimistic Lock	OptimisticLockException	Add @Version, handle retry
Cascade Issues	Orphan records, unexpected deletes	Review cascade types, use orphanRemoval
Slow Pagination	Full table scan for count	Use keyset pagination, DTO projections
Memory Issues	OOM on large result sets	Streaming, pagination, DTO projections

---

N+1 Problem

The Problem

// This executes 1 query for orders + N queries for customers
@Entity
public class Order {
    @ManyToOne(fetch = FetchType.LAZY)  // LAZY is correct default
    private Customer customer;
}

// Service code - triggers N+1
List<Order> orders = orderRepository.findAll();  // 1 query: SELECT * FROM orders
for (Order order : orders) {
    String name = order.getCustomer().getName();  // N queries: SELECT * FROM customers WHERE id = ?
}

Solution 1: JOIN FETCH

public interface OrderRepository extends JpaRepository<Order, Long> {

    @Query("SELECT o FROM Order o JOIN FETCH o.customer")
    List<Order> findAllWithCustomers();

    @Query("SELECT o FROM Order o JOIN FETCH o.customer WHERE o.status = :status")
    List<Order> findByStatusWithCustomer(@Param("status") OrderStatus status);
}

Solution 2: @EntityGraph

public interface OrderRepository extends JpaRepository<Order, Long> {

    @EntityGraph(attributePaths = {"customer", "items"})
    List<Order> findByStatus(OrderStatus status);

    // Named entity graph
    @EntityGraph("Order.withCustomerAndItems")
    List<Order> findAll();
}

@Entity
@NamedEntityGraph(
    name = "Order.withCustomerAndItems",
    attributeNodes = {
        @NamedAttributeNode("customer"),
        @NamedAttributeNode("items")
    }
)
public class Order {
    @ManyToOne(fetch = FetchType.LAZY)
    private Customer customer;

    @OneToMany(mappedBy = "order", fetch = FetchType.LAZY)
    private List<OrderItem> items;
}

Solution 3: Batch Fetching

// application.yml - global batch size
spring:
  jpa:
    properties:
      hibernate:
        default_batch_fetch_size: 20

// Or per-entity
@Entity
public class Order {
    @OneToMany(mappedBy = "order")
    @BatchSize(size = 20)  // Fetches up to 20 related collections in one query
    private List<OrderItem> items;
}

Detecting N+1

# Enable SQL logging to detect N+1 (development only!)
spring:
  jpa:
    show-sql: true
    properties:
      hibernate:
        format_sql: true

logging:
  level:
    org.hibernate.SQL: DEBUG
    org.hibernate.type.descriptor.sql.BasicBinder: TRACE

// Use Hibernate statistics
@Bean
public HibernatePropertiesCustomizer hibernateCustomizer() {
    return properties -> properties.put("hibernate.generate_statistics", "true");
}
// Watch for: "N queries executed" in logs

---

Lazy Loading

FetchType Basics

// DEFAULT fetch types:
@ManyToOne   // FetchType.EAGER by default - usually wrong!
@OneToOne    // FetchType.EAGER by default - usually wrong!
@OneToMany   // FetchType.LAZY by default - correct
@ManyToMany  // FetchType.LAZY by default - correct

Best Practice: Always Use LAZY

@Entity
public class Order {

    @ManyToOne(fetch = FetchType.LAZY)  // Override EAGER default
    @JoinColumn(name = "customer_id")
    private Customer customer;

    @OneToOne(fetch = FetchType.LAZY)   // Override EAGER default
    @JoinColumn(name = "shipping_id")
    private ShippingInfo shippingInfo;

    @OneToMany(mappedBy = "order", fetch = FetchType.LAZY)
    private List<OrderItem> items = new ArrayList<>();
}

LazyInitializationException Solutions

// Problem: Accessing lazy field outside transaction
@GetMapping("/orders/{id}")
public OrderResponse getOrder(@PathVariable Long id) {
    Order order = orderRepository.findById(id).orElseThrow();
    // Transaction is closed here
    order.getItems().size(); // LazyInitializationException!
}

// Solution 1: Fetch in query
@Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.id = :id")
Optional<Order> findByIdWithItems(@Param("id") Long id);

// Solution 2: DTO Projection (best for read-only)
@Query("SELECT new com.example.dto.OrderSummary(o.id, o.status, o.total) FROM Order o WHERE o.id = :id")
Optional<OrderSummary> findOrderSummary(@Param("id") Long id);

// Solution 3: @Transactional on service method
@Service
public class OrderService {
    @Transactional(readOnly = true)
    public OrderResponse getOrder(Long id) {
        Order order = orderRepository.findById(id).orElseThrow();
        // Transaction still open - lazy loading works
        return OrderResponse.from(order); // Map inside transaction
    }
}

---

Transactions

Basic Management

@Service
public class OrderService {

    // Read-only for queries - allows optimizations
    @Transactional(readOnly = true)
    public Order findById(Long id) {
        return orderRepository.findById(id).orElseThrow();
    }

    // Read-write for mutations
    @Transactional
    public Order createOrder(CreateOrderRequest request) {
        Order order = new Order();
        order.setCustomer(customerRepository.findById(request.customerId()).orElseThrow());
        order.setStatus(OrderStatus.CREATED);
        return orderRepository.save(order);
    }
}

Propagation

// REQUIRED (default) - Join existing or create new
@Transactional(propagation = Propagation.REQUIRED)
public void processOrder(Order order) { ... }

// REQUIRES_NEW - Always create new (suspend existing)
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void logAuditEvent(AuditEvent event) {
    // Commits even if outer transaction rolls back
    auditRepository.save(event);
}

// MANDATORY - Must run within existing transaction
@Transactional(propagation = Propagation.MANDATORY)
public void updateInventory(Order order) {
    // Throws if called without transaction
}

Common Mistakes

// BAD: Self-invocation - @Transactional is ignored!
@Service
public class OrderService {

    public void processOrder(Long orderId) {
        // This calls the method directly, bypassing the proxy
        // @Transactional on createShipment is IGNORED
        createShipment(orderId);
    }

    @Transactional
    public void createShipment(Long orderId) {
        // Not actually running in a transaction when called from processOrder!
    }
}

// GOOD: Inject self or extract to separate service
@Service
public class OrderService {
    private final ShipmentService shipmentService;  // Separate bean

    public void processOrder(Long orderId) {
        shipmentService.createShipment(orderId);  // Proxy is used
    }
}

@Service
public class ShipmentService {
    @Transactional
    public void createShipment(Long orderId) {
        // Transaction works correctly
    }
}

// BAD: Transaction too broad
@Transactional
public void processOrder(Order order) {
    validateOrder(order);
    Order saved = orderRepository.save(order);
    emailService.sendConfirmation(saved);  // Slow external call inside transaction!
    analyticsService.trackOrder(saved);    // Another slow call
}

// GOOD: Narrow transaction scope
@Transactional
public Order saveOrder(Order order) {
    validateOrder(order);
    return orderRepository.save(order);
}

public void processOrder(Order order) {
    Order saved = saveOrder(order);  // Transaction ends here
    emailService.sendConfirmation(saved);  // Outside transaction
    analyticsService.trackOrder(saved);
}

---

Entity Relationships

OneToMany / ManyToOne

@Entity
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItem> items = new ArrayList<>();

    // Helper methods to maintain both sides
    public void addItem(OrderItem item) {
        items.add(item);
        item.setOrder(this);
    }

    public void removeItem(OrderItem item) {
        items.remove(item);
        item.setOrder(null);
    }
}

@Entity
public class OrderItem {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "order_id", nullable = false)
    private Order order;

    private String productName;
    private int quantity;
    private BigDecimal price;
}

ManyToMany - Use Set, Not List

@Entity
public class Student {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // Use Set to avoid Hibernate bag issues with ManyToMany
    @ManyToMany(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
    @JoinTable(
        name = "student_course",
        joinColumns = @JoinColumn(name = "student_id"),
        inverseJoinColumns = @JoinColumn(name = "course_id")
    )
    private Set<Course> courses = new HashSet<>();

    public void addCourse(Course course) {
        courses.add(course);
        course.getStudents().add(this);
    }

    public void removeCourse(Course course) {
        courses.remove(course);
        course.getStudents().remove(this);
    }
}

@Entity
public class Course {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToMany(mappedBy = "courses")
    private Set<Student> students = new HashSet<>();
}

equals / hashCode for Entities

// Use business key or ID-based equality for entities
@Entity
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NaturalId
    @Column(nullable = false, unique = true)
    private String sku;

    // Use natural ID for equals/hashCode when available
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Product product = (Product) o;
        return Objects.equals(sku, product.sku);
    }

    @Override
    public int hashCode() {
        return Objects.hash(sku);
    }
}

// If no natural ID, use a consistent approach with generated ID:
@Entity
public class OrderItem {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        OrderItem that = (OrderItem) o;
        // Only equal if both have non-null IDs and they match
        return id != null && Objects.equals(id, that.id);
    }

    @Override
    public int hashCode() {
        // Constant hashCode ensures consistency before and after persist
        return getClass().hashCode();
    }
}

---

Query Optimization

Pagination

public interface OrderRepository extends JpaRepository<Order, Long> {

    // Spring Data pagination
    Page<Order> findByStatus(OrderStatus status, Pageable pageable);

    // Count query optimization - custom count
    @Query(value = "SELECT o FROM Order o WHERE o.status = :status",
           countQuery = "SELECT COUNT(o.id) FROM Order o WHERE o.status = :status")
    Page<Order> findByStatusOptimized(@Param("status") OrderStatus status, Pageable pageable);

    // Slice - no count query (better for infinite scroll)
    Slice<Order> findByCustomerId(Long customerId, Pageable pageable);
}

// Keyset pagination for large datasets
@Query("SELECT o FROM Order o WHERE o.createdAt < :cursor ORDER BY o.createdAt DESC")
List<Order> findOrdersBefore(@Param("cursor") LocalDateTime cursor, Pageable pageable);

DTO Projections

// Interface projection
public interface OrderSummary {
    Long getId();
    OrderStatus getStatus();
    BigDecimal getTotal();
    String getCustomerName();
}

public interface OrderRepository extends JpaRepository<Order, Long> {
    List<OrderSummary> findByStatus(OrderStatus status);
}

// Record projection (better performance)
public record OrderSummaryDto(Long id, OrderStatus status, BigDecimal total) {}

@Query("SELECT new com.example.dto.OrderSummaryDto(o.id, o.status, o.total) " +
       "FROM Order o WHERE o.status = :status")
List<OrderSummaryDto> findOrderSummaries(@Param("status") OrderStatus status);

Bulk Operations

public interface UserRepository extends JpaRepository<User, Long> {

    // Bulk update - bypasses entity lifecycle (no events, no cache update)
    @Modifying
    @Query("UPDATE User u SET u.active = false WHERE u.lastLoginAt < :cutoff")
    int deactivateInactiveUsers(@Param("cutoff") LocalDateTime cutoff);

    // Bulk delete
    @Modifying
    @Query("DELETE FROM User u WHERE u.active = false AND u.createdAt < :cutoff")
    int deleteInactiveUsers(@Param("cutoff") LocalDateTime cutoff);
}

// IMPORTANT: Call with @Transactional and clearAutomatically
@Modifying(clearAutomatically = true, flushAutomatically = true)
@Query("UPDATE User u SET u.active = false WHERE u.lastLoginAt < :cutoff")
int deactivateInactiveUsers(@Param("cutoff") LocalDateTime cutoff);

---

Optimistic Locking

@Entity
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Version
    private Long version;  // Hibernate auto-manages this

    private String name;
    private int stockQuantity;
}

// Handling optimistic lock failure
@Service
public class ProductService {

    @Transactional
    public Product updateStock(Long productId, int quantity) {
        try {
            Product product = productRepository.findById(productId).orElseThrow();
            product.setStockQuantity(product.getStockQuantity() - quantity);
            return productRepository.save(product);
        } catch (OptimisticLockException e) {
            throw new ConflictException("Product was modified by another transaction. Please retry.");
        }
    }

    // Retry pattern for optimistic locking
    @Retryable(value = OptimisticLockException.class, maxAttempts = 3)
    @Transactional
    public Product updateStockWithRetry(Long productId, int quantity) {
        Product product = productRepository.findById(productId).orElseThrow();
        product.setStockQuantity(product.getStockQuantity() - quantity);
        return productRepository.save(product);
    }
}

---

Common Mistakes

Cascade Misuse

// BAD: CascadeType.ALL on ManyToOne - deleting an order deletes the customer!
@Entity
public class Order {
    @ManyToOne(cascade = CascadeType.ALL)  // DANGEROUS
    private Customer customer;
}

// GOOD: Only cascade on the owning side (One side of OneToMany)
@Entity
public class Order {
    @ManyToOne(fetch = FetchType.LAZY)  // No cascade
    private Customer customer;

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItem> items;  // Cascade makes sense here
}

Missing Index

// BAD: Querying by fields without index
@Query("SELECT u FROM User u WHERE u.email = :email")
Optional<User> findByEmail(@Param("email") String email);
// Without index, this is a full table scan!

// GOOD: Add index annotation
@Entity
@Table(name = "users", indexes = {
    @Index(name = "idx_user_email", columnList = "email", unique = true),
    @Index(name = "idx_user_status_created", columnList = "status, created_at")
})
public class User {
    @Column(nullable = false, unique = true)
    private String email;
}

toString with Lazy Fields

// BAD: toString triggers lazy loading or LazyInitializationException
@Entity
public class Order {
    @OneToMany(mappedBy = "order")
    private List<OrderItem> items;

    @Override
    public String toString() {
        return "Order{id=" + id + ", items=" + items + "}"; // Triggers lazy load!
    }
}

// GOOD: Only include non-lazy fields in toString
@Override
public String toString() {
    return "Order{id=%d, status=%s, total=%s}".formatted(id, status, total);
}

---

Performance Checklist

• FetchType: All @ManyToOne and @OneToOne set to LAZY?
• N+1: List queries use JOIN FETCH or @EntityGraph?
• Pagination: List endpoints use Pageable?
• Projections: Read-only queries use DTOs instead of entities?
• Indexes: Frequently queried columns have indexes?
• Transactions: readOnly = true for query-only methods?
• Batch Size: default_batch_fetch_size configured?
• Bulk Operations: Mass updates use @Modifying queries?
• Version: Entities with concurrent access have @Version?
• Cascades: No CascadeType.ALL on @ManyToOne?
• Collections: @ManyToMany uses Set not List?
• equals/hashCode: Entities used in collections have proper implementations?