Spring Data JPA in five minutes: lessons from production

Spring Data JPA in five minutes: lessons from production

Building database persistence layers from scratch wastes time and introduces bugs that only surface under load. Spring Data JPA removes that friction by giving you CRUD operations, sorting, filtering, and pagination with minimal boilerplate—we've seen teams reduce repository code by 80% on real projects while maintaining full control when queries get complex.

In this guide, we'll walk through the patterns we use daily across e-commerce, SaaS, and trading platforms: how to structure repositories, leverage derived queries, handle pagination efficiently, and know when to drop down to custom SQL.

Extend JpaRepository<Entity, Id>

Spring Data JPA starts with one simple contract: create an interface that extends JpaRepository<T, ID>. That's it. You don't write an implementation—Spring generates one at runtime using proxies.

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
}

The moment you declare this interface, you inherit methods like save(), findById(), findAll(), delete(), and deleteById(). In a typical e-commerce flow—creating orders, updating customer profiles, removing expired sessions—this base set covers 60% of your queries.

// Injected in a service
@Autowired
private UserRepository userRepository;

// All of these are free
User user = new User("alice@example.com");
userRepository.save(user);

Optional<User> found = userRepository.findById(user.getId());

List<User> all = userRepository.findAll();

userRepository.deleteById(user.getId());

The JpaRepository interface already extends PagingAndSortingRepository, so you get pagination and sorting without extra setup. Under the hood, Spring uses the EntityManager to generate SQL—you can see it in logs with spring.jpa.show-sql=true.

Derived queries from method names

Beyond the basics, Spring Data JPA parses method names and builds queries automatically. Name your method right, and the framework generates the WHERE clause for you. This is where the real time savings kick in.

public interface UserRepository extends JpaRepository<User, Long> {
    // Finds a user by exact email match
    User findByEmail(String email);
    
    // Returns all users whose email contains the string
    List<User> findByEmailContaining(String partial);
    
    // Multiple conditions (AND)
    List<User> findByStatusAndCreatedAfter(String status, LocalDateTime date);
    
    // OR condition
    List<User> findByEmailOrPhone(String email, String phone);
    
    // Comparison operators
    List<User> findByAgeLessThan(int maxAge);
    List<User> findByCreatedBetween(LocalDateTime start, LocalDateTime end);
    
    // Ordering results
    List<User> findByStatusOrderByCreatedDesc(String status);
    
    // Exists check
    boolean existsByEmail(String email);
    
    // Count results
    long countByStatus(String status);
}

We've used this pattern on production ride-hailing systems to find drivers by location proximity (when combined with custom logic) and on SaaS platforms to query users by subscription tier and sign-up date. The readability matters: a method name like findByStatusAndCreatedAfter is self-documenting.

Spring recognizes keywords like And, Or, Between, LessThan, GreaterThan, Contains, Exists, OrderBy, Distinct, and more. The full list is in the Spring Data JPA documentation, but in practice, 90% of your queries will use a handful of these.

One caveat: derived queries work best for simple predicates. If your WHERE clause has nested conditions, multiple joins, or aggregations, a custom @Query is cleaner and more performant.

Paging and sorting built in

When listing users, orders, or products, you rarely want to fetch everything. Pagination is built into JpaRepository through the Pageable interface.

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Sort;

public interface UserRepository extends JpaRepository<User, Long> {
    Page<User> findByStatus(String status, Pageable pageable);
}

// In your service or controller
public Page<User> listActiveUsers(int pageNumber, int pageSize) {
    Pageable pageable = PageRequest.of(pageNumber, pageSize, Sort.by("createdAt").descending());
    return userRepository.findByStatus("ACTIVE", pageable);
}

// Usage from a REST endpoint
// /api/users?page=0&size=20&sort=createdAt,desc
Page<User> result = listActiveUsers(0, 20);
long total = result.getTotalElements();
int pages = result.getTotalPages();
List<User> content = result.getContent();

The Page object wraps your results with metadata: total element count, total page count, current page, and whether more pages exist. This eliminates a second COUNT query in most cases—Spring batches the count into the pagination query automatically.

For REST APIs, we often serialize Page directly. Spring Boot's @RestController handles it gracefully with Jackson, producing JSON like:

{
  "content": [...],
  "totalElements": 1500,
  "totalPages": 75,
  "currentPage": 0,
  "hasNext": true,
  "size": 20
}

Sorting is flexible. You can hardcode it (as shown above) or accept it from the client. Most teams accept it from query parameters to let the frontend control the order, but always validate the sort field against a whitelist to prevent SQL injection and unexpected performance impact.

Drop to @Query or JDBC when queries get complex

Not every query fits the derived query mold. When you need JOINs, GROUP BY, aggregations, or window functions, reach for @Query. This is where we distinguish between rapid prototyping and production-grade data access.

public interface OrderRepository extends JpaRepository<Order, Long> {
    
    // Custom JPQL query
    @Query("SELECT o FROM Order o WHERE o.user.email = :email AND o.status = :status")
    List<Order> findOrdersByUserEmailAndStatus(@Param("email") String email, @Param("status") String status);
    
    // With pagination
    @Query("SELECT o FROM Order o JOIN o.user u WHERE u.status = 'PREMIUM' ORDER BY o.createdAt DESC")
    Page<Order> findPremiumUserOrders(Pageable pageable);
    
    // Native SQL when JPQL gets awkward
    @Query(value = "SELECT o.* FROM orders o " +
                   "INNER JOIN users u ON o.user_id = u.id " +
                   "WHERE u.country = :country AND o.total > :minAmount " +
                   "ORDER BY o.created_at DESC", 
           nativeQuery = true)
    List<Order> findHighValueOrdersByCountry(@Param("country") String country, @Param("minAmount") BigDecimal minAmount);
}

JPQL (Java Persistence Query Language) is the preferred approach—it's database-agnostic and integrates with JPA's object mapping. Native SQL is your escape hatch when database-specific features (like window functions in PostgreSQL) are necessary or performance profiling shows a simpler SQL is significantly faster.

On a trading platform we worked on, we had a query that ranked users by portfolio performance within regions. Derived queries wouldn't express it cleanly, so we wrote native SQL with CTEs (common table expressions) and bound it to a @Query annotation. The result was readable, testable, and 10x faster than the ORM-generated alternative.

One pro tip: always add nativeQuery = true explicitly when using raw SQL. It's self-documenting and prevents mistakes.

Common mistakes

Mistake 1: N+1 queries from lazy loading. If your Order entity has a @OneToMany relationship to OrderItem, and you fetch 100 orders, you'll issue 101 queries by default. Use @Query with JOIN FETCH, or configure @Fetch(FetchMode.JOIN) on the relationship.

// Avoid N+1
List<Order> orders = orderRepository.findAll(); // 1 query
for (Order o : orders) {
    o.getItems().size(); // 100 more queries!
}

// Better: eagerly fetch with JOIN FETCH
@Query("SELECT DISTINCT o FROM Order o JOIN FETCH o.items WHERE o.user.id = :userId")
List<Order> findOrdersWithItems(@Param("userId") Long userId);

Mistake 2: Ignoring query performance. A derived query like findByCreatedBetweenAndStatusAndCategoryAndPrice... might generate a full table scan if columns aren't indexed. Always check the generated SQL and add database indexes for frequently queried fields.

Mistake 3: Passing unsanitized sort parameters. If you build Pageable from user input without validation, you expose yourself to NoSQL-style injection or unexpected table scans. Always whitelist allowed sort fields.

// Unsafe
String sortField = request.getParameter("sort");
Pageable pageable = PageRequest.of(0, 20, Sort.by(sortField));

// Safe
Set<String> allowedFields = Set.of("createdAt", "price", "name");
String sortField = request.getParameter("sort");
if (!allowedFields.contains(sortField)) {
    sortField = "createdAt"; // fallback
}
Pageable pageable = PageRequest.of(0, 20, Sort.by(sortField));

Mistake 4: Returning large result sets. Even with pagination, if you use findAll() without Pageable, you risk loading thousands of rows into memory. Always paginate when the table grows beyond a few hundred records.

Key takeaways

• Extend JpaRepository<Entity, Id> to get CRUD, pagination, and sorting for free. You write zero SQL for basic operations.
• Use derived query method names for simple predicates: findByEmailAndStatus() reads like documentation and performs well when indexes exist.
• Leverage Pageable and Page for REST endpoints. Spring serializes them correctly, and pagination metadata is included automatically.
• Drop to @Query with JPQL or native SQL for complex queries, joins, and aggregations. JPQL is preferred for portability; native SQL when you need database-specific features.
• Watch for N+1 queries from lazy loading relationships. Use JOIN FETCH or explicit eager loading.
• Index your database columns and validate sort parameters. Performance at scale depends on both the ORM and the database underneath.