Spring Boot Course · Lesson 5

Persistence with Spring Data JPA

Your books live in a ConcurrentHashMap that vanishes the moment the app restarts. Time to give them a real home. In this lesson you'll add a database, turn Book into a persistent entity, and replace your hand-written store with a repository Spring Data writes for you — most of it without a single line of SQL.

The cast: JPA, Hibernate, Spring Data

Three names show up the moment you persist data in Spring. They're often blurred together, so let's separate them once:

• JPA (Jakarta Persistence API) — a specification: a set of interfaces and annotations (@Entity, @Id, …) describing how Java objects map to database rows. It's a contract, not an implementation.
• Hibernate — the implementation of that spec that actually does the work: generating SQL, tracking changes, mapping rows to objects. It's the default ORM (object-relational mapper) under Spring Boot.
• Spring Data JPA — a Spring layer on top of Hibernate that removes the boilerplate. You declare a repository interface; Spring Data generates the implementation at runtime.

You'll mostly talk to the top layer (Spring Data) and let it drive the two below. One starter wires all three together.

Step 1 — Add the dependencies

Open pom.xml and add: the JPA starter, the PostgreSQL driver, Liquibase (for schema migrations), Spring Boot's Docker Compose support, Lombok (to keep the entity tidy), and a UUIDv7 generator.

pom.xml — inside <dependencies>

<!-- Spring Data JPA + Hibernate -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

<!-- PostgreSQL JDBC driver (used at runtime to talk to the database) -->
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

<!-- Liquibase migrations. The autoconfiguration lives in this module (it brings
     liquibase-core transitively); the bare org.liquibase:liquibase-core won't activate it. -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-liquibase</artifactId>
</dependency>

<!-- Starts/stops the Postgres container from compose.yaml when the app runs -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-docker-compose</artifactId>
    <optional>true</optional>
</dependency>

<!-- Lombok: generates getters/constructors/equals at compile time -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

<!-- uuid-creator: time-ordered UUIDv7 generation -->
<dependency>
    <groupId>com.github.f4b6a3</groupId>
    <artifactId>uuid-creator</artifactId>
    <version>6.0.0</version>  <!-- or the latest on Maven Central -->
</dependency>

Step 2 — Turn Book into an entity

Here's the first real change to your model. Since Lesson 2, Book has been a record — a perfect immutable data carrier. But a JPA entity can't be a record: Hibernate needs a no-arg constructor, mutable fields it can populate, and a non-final class it can subclass with a proxy. So the entity becomes a class. (Records aren't gone — they return in Lesson 6 as DTOs, the immutable shape of your API.)

src/main/java/com/example/library/book/Book.java

package com.example.library.book;

import java.util.UUID;
import com.github.f4b6a3.uuid.UuidCreator;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import lombok.AccessLevel;
import lombok.EqualsAndHashCode;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

@Entity
@Getter
@Setter
@NoArgsConstructor(access = AccessLevel.PROTECTED)   // JPA needs it; protected discourages app code from using it
@EqualsAndHashCode(onlyExplicitlyIncluded = true)    // identity is the id, and ONLY the id
public class Book {

    @Id
    @EqualsAndHashCode.Include
    private UUID id = UuidCreator.getTimeOrderedEpoch();   // a fresh UUIDv7, set at construction

    private String title;
    private String author;
    private int year;

    // App-facing constructor: supply the data; the id defaults to a new UUIDv7 above.
    public Book(String title, String author, int year) {
        this.title = title;
        this.author = author;
        this.year = year;
    }
}

@Entity tells JPA "map this class to a database table." @Id marks the primary key. The field initializer assigns a time-ordered UUIDv7 the instant a Book is constructed — so every entity has a stable, non-null id from birth, before it ever touches the database.

Book b = new Book("Clean Code", "Robert C. Martin", 2008);
Set<Book> shelf = new HashSet<>();
shelf.add(b);        // hash from title+author+year → bucket A
b.setYear(2009);     // a fix; hash changes → "should" be bucket B
shelf.contains(b);   // false!  it's in bucket A; we looked in B

Step 3 — Declare the repository

This is the part that feels like magic the first time. You write an interface — no implementation — and Spring Data provides a working one at runtime:

src/main/java/com/example/library/book/BookRepository.java

package com.example.library.book;

import java.util.List;
import java.util.UUID;
import org.springframework.data.jpa.repository.JpaRepository;

public interface BookRepository extends JpaRepository<Book, UUID> {

    // A derived query: Spring Data reads the method NAME and writes the SQL.
    List<Book> findByAuthor(String author);
}

JpaRepository<Book, UUID> says "a repository of Book entities whose id type is UUID." That single line of inheritance hands you save, findById, findAll, deleteById, existsById, count, and more — all implemented. You only add method signatures for the queries unique to your domain.

Step 4 — Point the service at the repository

Now retire the ConcurrentHashMap. The service stops being the storage and starts delegating to it — exactly the relationship the controller already has with the service. Notice it still injects its dependency through the constructor (Lesson 3), and its method signatures don't change at all:

src/main/java/com/example/library/book/BookService.java

package com.example.library.book;

import java.util.List;
import java.util.Optional;
import java.util.UUID;
import com.github.f4b6a3.uuid.UuidCreator;
import org.springframework.stereotype.Service;

@Service
public class BookService {

    private final BookRepository books;

    public BookService(BookRepository books) {   // a repository bean, injected
        this.books = books;
    }

    public List<Book> findAll() {
        return books.findAll();
    }

    public Optional<Book> findById(UUID id) {
        return books.findById(id);
    }

    public Book create(Book incoming) {
        incoming.setId(UuidCreator.getTimeOrderedEpoch());   // the server owns identity — never trust a client-sent id
        return books.save(incoming);
    }

    public Optional<Book> replace(UUID id, Book incoming) {
        if (!books.existsById(id)) {
            return Optional.empty();
        }
        incoming.setId(id);                  // pin the path id, then upsert
        return Optional.of(books.save(incoming));
    }

    public boolean delete(UUID id) {
        if (!books.existsById(id)) {
            return false;
        }
        books.deleteById(id);
        return true;
    }
}

That's the data layer done. One mechanical edit remains — and it's the only change the controller needs. Because Book is a class now, the create method reads the new id with the getter getId() instead of the record accessor id(). Update that one line:

src/main/java/com/example/library/book/BookController.java

@PostMapping                                // POST /api/books
public ResponseEntity<Book> create(@RequestBody Book incoming) {
    Book saved = books.create(incoming);
    URI location = URI.create("/api/books/" + saved.getId());   // was saved.id()
    return ResponseEntity.created(location).body(saved);
}

Miss this and the build stops with cannot find symbol: method id() — the record's id() is gone, replaced by the getter. (Same applies to any other .title()/.author()/.year() you might have: they're .getTitle()/etc. now.)

Step 5 — Describe the database in compose.yaml

Create a compose.yaml in the project root (next to pom.xml). It declares one service — a Postgres container — with a database name, a user, a password, and a named volume so the data survives between runs:

compose.yaml

services:
  postgres:
    image: 'postgres:18'
    environment:
      - 'POSTGRES_DB=library'
      - 'POSTGRES_USER=library'
      - 'POSTGRES_PASSWORD=library'
    ports:
      - '5432:5432'          # expose the DB on localhost so psql can reach it
    volumes:
      - 'library-data:/var/lib/postgresql'   # persist data across restarts

volumes:
  library-data:

spring.datasource.url=jdbc:postgresql://db.internal:5432/library
spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASSWORD}

So application.properties stays tiny. Liquibase owns the schema (Step 6), so Hibernate must not touch it — validate tells Hibernate to only check that your entities match the tables Liquibase built, and change nothing:

src/main/resources/application.properties

# Hibernate never alters the schema - Liquibase owns it. Just verify entities match the tables.
spring.jpa.hibernate.ddl-auto=validate

# Log SQL through SLF4J, pretty-printed, with bound parameter values
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.orm.jdbc.bind=TRACE
spring.jpa.properties.hibernate.format_sql=true

Step 6 — Put the schema under version control with Liquibase

Building the schema is Liquibase's job, not Hibernate's. You describe each schema change as a changeset inside a changelog, and Liquibase applies them in order, exactly once each, recording what it has run — so your schema becomes versioned, reviewable code you can replay on any fresh database. (That's the point of the validate setting from Step 5: Hibernate verifies your entities match the schema Liquibase built, rather than creating or altering anything itself.)

Spring Boot runs Liquibase automatically on startup, looking for a master changelog at a conventional path. Create it — it's just an index that includes the real change files:

src/main/resources/db/changelog/db.changelog-master.yaml

databaseChangeLog:
  - include:
      file: changes/001-create-book-table.yaml
      relativeToChangelogFile: true

Now the first migration — it creates the book table your entity maps to:

src/main/resources/db/changelog/changes/001-create-book-table.yaml

databaseChangeLog:
  - changeSet:
      id: 001-create-book-table
      author: roman
      changes:
        - createTable:
            tableName: book
            columns:
              - column:
                  name: id
                  type: uuid
                  constraints:
                    primaryKey: true
                    nullable: false
              - column:
                  name: title
                  type: varchar(255)
              - column:
                  name: author
                  type: varchar(255)
              - column:
                  name: year
                  type: int

Step 7 — (Optional) seed some books

Because the database is empty the first time you start it, GET /api/books returns [] until you add something. To put the familiar three classics in on startup, add a tiny seeder — a bean that runs when the app boots. The count() > 0 guard means it seeds only once: on later runs your persisted data is already there, so it does nothing.

src/main/java/com/example/library/book/BookSeeder.java

package com.example.library.book;

import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

@Component
public class BookSeeder implements CommandLineRunner {

    private final BookRepository books;

    public BookSeeder(BookRepository books) {
        this.books = books;
    }

    @Override
    public void run(String... args) {
        if (books.count() > 0) return;   // don't double-seed
        books.save(new Book("Clean Code", "Robert C. Martin", 2008));
        books.save(new Book("Effective Java", "Joshua Bloch", 2018));
        books.save(new Book("The Pragmatic Programmer", "Hunt & Thomas", 1999));
    }
}

CommandLineRunner is a Spring hook: any bean implementing it has its run method called once, after the context is ready. Each new Book(...) gets its own UUIDv7 from the constructor — so the ids are real, time-ordered, and assigned before save ever runs.

Step 8 — Run it and watch it boot

One bit of config first: run the app in UTC. Running a backend in UTC is standard practice — timestamps and logs mean the same thing no matter where the machine is — and it sidesteps host-timezone surprises (some OS zone names trip up the JDBC connection on newer Postgres). Set it once in the Spring Boot Maven plugin so every ./mvnw spring-boot:run uses it:

pom.xml — configure the existing spring-boot-maven-plugin

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <jvmArguments>-Duser.timezone=UTC</jvmArguments>
    </configuration>
</plugin>

Now make sure Docker Desktop is running, then start the app (./mvnw spring-boot:run). Watch the order in the console: Spring Boot brings up the Postgres container and connects, Liquibase applies 001-create-book-table (creating the table), Hibernate then validates that Book matches it, and finally the seeder inserts. Every later run, Liquibase sees the changeset already applied and skips it. Now exercise it:

# List the seeded books — now coming from a real SQL query.
curl -i http://localhost:8080/api/books

# Add one. Hibernate runs an INSERT; the response shows the server-assigned UUIDv7 id.
curl -i -X POST http://localhost:8080/api/books \
  -H "Content-Type: application/json" \
  -d '{"title":"Refactoring","author":"Martin Fowler","year":2018}'

@SpringBootTest
@Disabled("Needs a test database; wired up with Testcontainers in the testing lesson.")
class LibraryApplicationTests {
    @Test void contextLoads() { }
}

# Connect through the published port with the local psql client…
PGPASSWORD=library psql -h localhost -p 5432 -U library -d library -c 'SELECT * FROM book;'

# …or exec psql inside the container — no password needed (local socket connections are trusted):
docker compose exec postgres psql -U library -d library -c 'SELECT * FROM book;'

Step 9 — Use the derived query: search by author

You added findByAuthor to the repository; let's expose it. Rather than a new endpoint, take an optional query parameter on the existing collection route. But where does the decision — "filter, or return everything?" — belong? Not the controller. Choosing which query to run based on the input is business logic, so it lives in the service; the controller just passes the parameter along. Add the method to the service:

src/main/java/com/example/library/book/BookService.java

// Optionally filter by author — the "which query?" decision lives here, not in the controller.
public List<Book> findAll(String author) {
    return (author == null) ? findAll() : books.findByAuthor(author);
}

Now the controller stays a thin translator: read the optional query parameter, hand it to the service, return the result. @RequestParam binds a ?author=... value from the URL's query string:

@GetMapping                                          // GET /api/books  or  /api/books?author=...
public List<Book> all(@RequestParam(required = false) String author) {
    return books.findAll(author);                    // books = the BookService
}

With required = false, the parameter is optional: no ?author= means "list everything," while ?author=Joshua%20Bloch runs your derived query. One endpoint, two behaviours, zero SQL. Restart the app and try both:

# No filter — every book
curl -i http://localhost:8080/api/books

# Filtered — just this author, via your derived query
curl -i "http://localhost:8080/api/books?author=Joshua%20Bloch"

Check yourself

Retrieval beats re-reading. Answer from memory before clicking.

Read this next

Primary source: the Spring reference on Defining Query Methods — the official rules for how a repository method name becomes a query. Skim the keyword tables (Containing, GreaterThan, OrderBy, …); they're the toolbox you'll reach into constantly.

New vocabulary from this lesson lives in the Glossary — your quick-reference for every term we use.