303-frameworks-spring-data-jdbc

Spring Data JDBC with Records

Spring Data JDBC provides a simpler alternative to JPA, offering direct SQL control while maintaining Spring's repository abstractions. When combined with Java records, it creates clean, immutable data models perfect for modern Java applications.

Implementing These Principles

These guidelines are built upon the following core principles:

• Immutability: Use records for immutable entities that are thread-safe and predictable
• Simplicity: Leverage Spring Data JDBC's straightforward approach over complex ORM mapping
• Constructor Injection: Always use constructor-based dependency injection for better testability
• Transaction Boundaries: Keep transactions at the service layer, not repository layer
• SQL Control: Use custom queries when needed for optimal performance

Table of contents

• Rule 1: Use Records for Entity Classes
• Rule 2: Implement Repository Pattern Correctly
• Rule 3: Handle Updates with Immutable Records
• Rule 4: Design Aggregate Relationships Properly
• Rule 5: Use Custom Queries for Complex Operations
• Rule 6: Implement Proper Transaction Management
• Rule 7: Embrace Single Query Loading to Eliminate N+1 Problems

Rule 1: Use Records for Entity Classes

Title: Prefer Records Over Classes for Entity Definitions Description: Records provide immutability, automatic equals/hashCode, and clean constructor-based mapping that works perfectly with Spring Data JDBC. They eliminate boilerplate code and ensure thread safety. Use @PersistenceCreator when you have multiple constructors to specify which one Spring Data JDBC should use. Use @Column to explicitly map record fields to database columns, especially when field names differ from column names.

Good example:

public record Customer(
    @Id 
    @Column("customer_id") 
    Long id,
    
    @Column("first_name") 
    String firstName,
    
    @Column("last_name") 
    String lastName,
    
    @Column("email_address") 
    String email,
    
    @Column("created_at") 
    LocalDateTime createdAt
) {
    // Constructor for Spring Data JDBC (explicit annotation when multiple constructors exist)
    @PersistenceCreator
    public Customer(Long id, String firstName, String lastName, String email, LocalDateTime createdAt) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.email = email;
        this.createdAt = createdAt;
    }
    
    // Factory method for new entities
    public static Customer of(String firstName, String lastName, String email) {
        return new Customer(null, firstName, lastName, email, LocalDateTime.now());
    }
}