Java Records & JPA: The Compatibility Guide

Overview

Java Records are a compelling choice for data-carrying types: concise, immutable, and expressive. But they are fundamentally incompatible with JPA's @Entity requirement. Hibernate needs to subclass your entity to create lazy-loading proxies, and it needs a no-args constructor to instantiate entities via reflection. Records are final classes with no no-args constructor — both requirements are violated. The good news: Records excel as DTOs and projections in Hibernate 6, where they are directly supported.

1. 01

   Keep @Entity classes as standard POJOs (or use Lombok @Data/@Builder to reduce boilerplate).

2. 02

   Use Records as DTOs in your API layer — they are perfect for immutable request/response bodies.

3. 03

   Use Records as constructor expression targets in JPQL: SELECT new com.example.dto.UserDto(u.id, u.name) FROM User u.

4. 04

   Use Records as Spring Data interface projection types — Hibernate 6 maps them automatically.

5. 05

   Use @Embeddable Records for value objects (Address, Money) in Hibernate 6.2+ — this is officially supported.

// ❌ ILLEGAL — Record cannot be a JPA Entity
class="hi-ann">@Entity
public record UserEntity(class="hi-ann">@Id Long id, String email) {}

// ✅ CORRECT — Standard POJO Entity (with Lombok)
class="hi-ann">@Entity
class="hi-ann">@Table(name = "users")
class="hi-ann">@Getter class="hi-ann">@Setter class="hi-ann">@NoArgsConstructor
public class User {
    class="hi-ann">@Id class="hi-ann">@GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;
}

// ✅ RECORD AS DTO (API response — perfect use case)
public record UserDto(Long id, String name) {}

// ✅ RECORD IN JPQL CONSTRUCTOR EXPRESSION (Hibernate 6+)
class="hi-ann">@Query("""
    SELECT new com.example.dto.UserDto(u.id, u.name)
    FROM User u WHERE u.active = true
""")
List<UserDto> findActiveUsers();

// ✅ RECORD AS @Embeddable (Hibernate 6.2+ supported!)
class="hi-ann">@Embeddable
public record Address(String street, String city, String postcode) {}

class="hi-ann">@Entity
public class User {
    class="hi-ann">@Id private Long id;
    class="hi-ann">@Embedded private Address address; // Record embedded directly!
}

1. 01

   Use MapStruct to generate compile-time safe Entity-to-Record mappers — avoid manual field-by-field copying in service methods.

2. 02

   Define all API request/response types as Records — they enforce immutability and eliminate defensive copying.

3. 03

   Use Records as constructor projection targets in JPQL instead of full entity loads for any read-only endpoint.

What causes Java Records & JPA: The Compatibility Guide in Spring Boot 3?

JPA mandates that entity classes be non-final (Hibernate must subclass them to generate proxies for lazy loading), have a no-args constructor (Hibernate uses reflection to instantiate them), and support mutable state (Hibernate's dirty-checking mechanism modifies field values). All three requirements are directly violated by Java Records.

How do I fix Java Records & JPA: The Compatibility Guide?

Keep @Entity classes as standard POJOs (or use Lombok @Data/@Builder to reduce boilerplate). Use Records as DTOs in your API layer — they are perfect for immutable request/response bodies. Use Records as constructor expression targets in JPQL: SELECT new com.example.dto.UserDto(u.id, u.name) FROM User u. Use Records as Spring Data interface projection types — Hibernate 6 maps them automatically. Use @Embeddable Records for value objects (Address, Money) in Hibernate 6.2+ — this is officially supported.

Best practice #1 for preventing Java 21 · JPA errors?

Use MapStruct to generate compile-time safe Entity-to-Record mappers — avoid manual field-by-field copying in service methods.

Best practice #2 for preventing Java 21 · JPA errors?

Define all API request/response types as Records — they enforce immutability and eliminate defensive copying.

Best practice #3 for preventing Java 21 · JPA errors?

Use Records as constructor projection targets in JPQL instead of full entity loads for any read-only endpoint.