Building a Production-Ready Persistence Layer in Spring Boot

Spring Data JPA makes persistence remarkably easy to get started with.

Define an entity, create a repository, extend JpaRepository, and you already have CRUD operations, pagination, sorting, and a powerful query abstraction.

public interface CustomerRepository
    extends JpaRepository<Customer, Long> {
}

For a small application, this may be all you need.

But as a Spring Boot application grows, persistence requirements rarely remain that simple.

You start adding audit fields to entities. Search endpoints require increasingly complex filters. Repository interfaces accumulate query methods. Specifications appear in multiple places. Different services implement pagination and filtering differently.

Eventually, the problem is no longer:

How do I persist an entity?

It becomes:

How do I build a persistence layer that remains consistent, reusable, and maintainable as the application grows?

That is the problem a production-ready persistence foundation should solve.

---

The Persistence Layer Grows Faster Than You Expect

Consider a typical Spring Boot application.

You might begin with a repository like this:

public interface CustomerRepository
    extends JpaRepository<Customer, Long> {

  List<Customer> findByStatus(CustomerStatus status);
}

Then another requirement appears.

List<Customer> findByStatusAndCountry(
    CustomerStatus status,
    String country);

Then another.

List<Customer> findByStatusAndCountryAndType(
    CustomerStatus status,
    String country,
    CustomerType type);

Soon the API needs optional filters:

GET /customers
    ?status=ACTIVE
    &country=PH
    &type=PREMIUM

Each parameter may or may not be present.

Creating a repository method for every possible combination quickly becomes impractical.

At the same time, other concerns start appearing across your entities:

createdAt
updatedAt
createdBy
updatedBy

Pagination needs to behave consistently.

Sorting needs validation.

Specifications need common utilities.

Some queries should return full entities, while others only need a subset of fields.

None of these problems is particularly difficult on its own.

The problem is that they appear repeatedly.

---

Repetition Is Often a Sign of Missing Infrastructure

A common response is to create utility classes whenever duplication appears.

One helper for specifications.

Another for pagination.

A base entity for auditing.

Some repository helpers.

A few mapper utilities.

This works initially.

But across multiple applications or microservices, these implementations tend to evolve independently.

One service handles auditing one way.

Another uses a slightly different base entity.

Another builds specifications directly inside its service layer.

Another exposes entities from repository queries because creating a proper projection feels like too much work.

The individual decisions may all be reasonable.

The inconsistency is the problem.

A persistence foundation should establish a small set of conventions that application code can build upon.

Not a framework that replaces Spring Data JPA.

Not another abstraction hiding Hibernate.

Just enough reusable infrastructure to remove repetitive persistence plumbing.

---

Start with Consistent Entity Models

Most business entities need some common persistence metadata.

For example:

@MappedSuperclass
public abstract class AuditableModel {

  @CreatedDate
  private Instant createdAt;

  @LastModifiedDate
  private Instant updatedAt;

  @CreatedBy
  private String createdBy;

  @LastModifiedBy
  private String updatedBy;
}

Then business entities can focus on business data:

@Entity
public class Customer extends AuditableModel {

  @Id
  @GeneratedValue
  private Long id;

  private String name;

  private String country;

  @Enumerated(EnumType.STRING)
  private CustomerStatus status;
}

The important part is not saving four fields.

The important part is establishing a predictable model across the application.

When every persisted entity follows the same conventions, infrastructure becomes easier to build around it.

Operations teams know where to find creation and modification information.

Developers do not need to reinvent auditing for every entity.

Support investigations become easier because persistence metadata is consistent.

Consistency is one of the less glamorous benefits of shared infrastructure, but in production systems it is often one of the most valuable.

---

Dynamic Queries Should Be Composable

Repository query methods are excellent when the query is fixed.

For example:

Optional<Customer> findByExternalId(String externalId);

There is nothing wrong with this.

Problems begin when repository methods are used to represent every possible combination of optional search parameters.

This:

findByStatusAndCountryAndType(...)

eventually becomes:

findByStatusAndCountryAndTypeAndCreatedAtBetween(...)

and then multiple variations of the same method appear because some filters are optional.

For dynamic search requirements, queries should instead be composed from individual conditions.

Spring Data JPA already provides an excellent abstraction for this:

Specification<T>

A condition can be represented independently:

Specification<Customer> hasStatus(CustomerStatus status)

Another condition can handle country:

Specification<Customer> hasCountry(String country)

And another can represent customer type:

Specification<Customer> hasType(CustomerType type)

These can then be composed:

Specification<Customer> specification =
    Specification.where(hasStatus(status))
        .and(hasCountry(country))
        .and(hasType(type));

Now the query structure follows the actual search model rather than the number of possible parameter combinations.

This becomes especially useful when building REST APIs with optional filtering.

---

Specifications Should Be Reusable Too

Using Specification solves the query-combination problem, but large applications can still accumulate repetitive specification code.

You repeatedly write predicates for:

• equality
• IN
• ranges
• dates
• strings
• null checks
• relationships

At that point, the same principle applies again.

The application should define what it wants to filter.

The persistence infrastructure should handle the repetitive mechanics of building those predicates.

The goal is not to hide JPA.

It is to keep application-specific query logic readable.

A specification should tell you something meaningful about the domain:

CustomerSpecifications.activeCustomers()

or:

CustomerSpecifications.createdBetween(from, to)

rather than forcing every developer to repeatedly reconstruct the same Criteria API plumbing.

---

Don't Load an Entire Entity When You Don't Need It

Another persistence problem appears when reads become more complex.

Suppose a Customer entity eventually contains dozens of fields and several relationships.

A search endpoint might only need:

id
name
status
country
createdAt

Returning the complete entity is unnecessary.

It can also create additional problems:

• unnecessary data retrieval
• accidental lazy loading
• larger persistence contexts
• unwanted entity serialization
• tighter coupling between APIs and database models

This is where projections become valuable.

For example:

public interface CustomerSummary {

  Long getId();

  String getName();

  CustomerStatus getStatus();

  String getCountry();

  Instant getCreatedAt();
}

The persistence layer can retrieve the representation required by the use case rather than always materializing the complete entity.

This also reinforces an important architectural principle:

A persisted entity is not automatically the correct model for every read operation.

Entities, DTOs, and projections serve different purposes.

A good persistence foundation should make those distinctions easy to maintain.

---

Pagination and Sorting Are Infrastructure Concerns

Pagination looks simple:

PageRequest.of(page, size)

But APIs eventually need consistent behavior around:

• default page size
• maximum page size
• allowed sorting fields
• sort direction
• multiple sort fields
• invalid parameters

If every endpoint independently interprets these rules, subtle inconsistencies appear.

One API may treat page numbering as zero-based.

Another may expose one-based pagination.

One endpoint may allow arbitrary sorting.

Another validates fields.

A reusable persistence layer gives applications a common foundation for these mechanics while leaving business-specific decisions in the application.

Again, the objective is not more abstraction.

It is less repetition.

---

A Persistence Library Should Work With Spring Data, Not Against It

There is a danger when creating reusable infrastructure.

It is easy to keep adding abstractions until developers can no longer recognize the framework underneath them.

A persistence library should not require developers to forget how Spring Data JPA works.

If a developer knows:

JpaRepository

JpaSpecificationExecutor

Specification

Pageable

those concepts should remain useful.

The library should provide reusable building blocks around those APIs rather than replacing them with an entirely different persistence model.

This matters for another reason: debugging.

When something goes wrong in production, developers should be able to follow the execution path from the application to Spring Data to Hibernate to the database.

Infrastructure that removes boilerplate is useful.

Infrastructure that hides behavior is much harder to support.

---

This Is Why I Built NERV Persistence

These are the problems that led to nerv-persistence.

NERV Persistence is an open-source persistence foundation for Spring Boot applications built on top of Spring Data JPA.

It provides reusable building blocks for concerns that tend to appear repeatedly in real applications, including:

• common persistence models
• auditable entities
• reusable specification infrastructure
• dynamic querying
• projections
• repository conventions
• consistent persistence patterns

The intention is deliberately conservative.

NERV Persistence does not try to replace Spring Data JPA or Hibernate.

It builds on them.

Application developers should still recognize the underlying Spring concepts and be able to use them directly when necessary.

The library simply provides a common foundation so every application does not have to rebuild the same persistence infrastructure from scratch.

---

Where NERV Persistence Fits

A typical Spring Boot application might look something like this:

Application
    |
    +-- REST / API
    |
    +-- Application Services
    |
    +-- DTOs / Mappers
    |
    +-- Domain Logic
            |
            v
    NERV Persistence
            |
            +-- Persistence Models
            +-- Specifications
            +-- Query Infrastructure
            +-- Projections
            +-- Repository Foundation
                    |
                    v
            Spring Data JPA
                    |
                    v
                Hibernate
                    |
                    v
                Database

NERV Persistence sits close to the persistence boundary.

It should not contain your business rules.

It should not determine your domain model.

And it should not force every service to use identical database structures.

Instead, it standardizes the technical concerns that are genuinely reusable.

---

Why This Matters More in Microservices

Persistence duplication becomes particularly noticeable in a microservice architecture.

Imagine several services:

customer-service
payment-service
order-service
subscription-service
notification-service

Each service owns its database and domain model.

That independence is important.

But independence does not mean every service needs a different implementation of:

auditing
pagination
specifications
query helpers
repository conventions

These are infrastructure concerns.

A shared persistence foundation allows teams to standardize them while keeping domain-specific persistence inside each service.

The distinction is important:

Share infrastructure conventions, not domain models.

A Customer entity should not become a shared library just because several services know what a customer is.

But the infrastructure used to audit, query, paginate, and persist entities can often be shared safely.

---

Production-Ready Doesn't Mean Complicated

A production-ready persistence layer does not need hundreds of abstractions.

In fact, the opposite is often true.

Good persistence infrastructure should make the common path boring:

define entity
    ↓
define repository
    ↓
compose query
    ↓
retrieve the required model
    ↓
map to application response

The complexity should remain visible only when the use case actually requires it.

That is the philosophy behind NERV Persistence and, more broadly, the NERV libraries.

Build reusable infrastructure around problems that repeatedly appear in production systems, while keeping the underlying technology understandable and debuggable.

---

What's Next?

This article provides the broader architecture behind NERV Persistence.

In the next articles, we'll go deeper into individual persistence problems, including:

1. dynamic queries without repository method explosion
2. composable Spring Data JPA specifications
3. auditable base entities
4. projections and efficient read models
5. reusable pagination, sorting, and filtering
6. entity vs DTO vs projection
7. designing base JPA entities without over-abstracting
8. reusable repository infrastructure
9. consistent persistence patterns across Spring Boot services

Each topic will focus on the engineering problem first and then show how it can be implemented using Spring Data JPA and NERV Persistence.

---

NERV Persistence

nerv-persistence is part of the NERV open-source ecosystem — Next-Generation Engineering for Runtime Velocity — a collection of Spring libraries focused on reusable infrastructure for production applications.

If you're building Spring Boot applications and repeatedly implementing the same persistence infrastructure across projects or services, NERV Persistence is intended to provide a reusable starting point.

Explore the project on GitHub:
https://github.com/czetsuyatech/nerv-persistence

More NERV libraries and engineering articles:
https://www.czetsuyatech.com/