Week 5: Data Persistence with Spring Data JPA (Part 2)

1. Modeling Relationships

Week 4's Task stood alone. Most domains don't — a task belongs to a project, an order has line items, a user has roles. JPA models these with relationship annotations that map directly onto foreign keys, and getting the owning side right is the single most important decision you'll make when wiring two entities together.

@ManyToOne / @OneToMany

A Project can have many Tasks, and each Task belongs to exactly one Project — a classic one-to-many. The foreign key lives on the "many" side (the tasks table gets a project_id column), so Task is the owning side and declares the @ManyToOne. Project is the inverse side: it declares @OneToMany(mappedBy = "project"), pointing back at the field name on Task that owns the relationship rather than defining a second foreign key of its own.

package com.codeverse.week05.project;

import com.codeverse.week05.task.Task;
import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.List;

@Entity
@Table(name = "projects")
public class Project {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String name;

    // Inverse side -- Task owns the relationship via its "project" field.
    // mappedBy means "no foreign key here, look at Task.project instead."
    @OneToMany(mappedBy = "project", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<Task> tasks = new ArrayList<>();

    protected Project() {}

    public Project(String name) {
        this.name = name;
    }

    public void addTask(Task task) {
        tasks.add(task);
        task.setProject(this);
    }

    public Long getId() { return id; }
    public String getName() { return name; }
    public List<Task> getTasks() { return tasks; }
}

package com.codeverse.week05.task;

import com.codeverse.week05.project.Project;
import jakarta.persistence.*;

@Entity
@Table(name = "tasks")
public class Task {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String title;

    private boolean completed;

    // Owning side -- this field is what actually creates the
    // "project_id" foreign key column on the tasks table.
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "project_id")
    private Project project;

    protected Task() {}

    public Task(String title, Project project) {
        this.title = title;
        this.project = project;
    }

    public void setProject(Project project) { this.project = project; }
    public Project getProject() { return project; }
    public Long getId() { return id; }
    public String getTitle() { return title; }
    public boolean isCompleted() { return completed; }
}

A quick look at @ManyToMany

If a Task can carry several free-form Tags, and a Tag like "urgent" can apply to many tasks, that's a many-to-many — JPA backs it with a hidden join table rather than a foreign key on either side:

@ManyToMany
@JoinTable(
    name = "task_tags",
    joinColumns = @JoinColumn(name = "task_id"),
    inverseJoinColumns = @JoinColumn(name = "tag_id")
)
private Set<Tag> tags = new HashSet<>();

We won't build out Tag fully this week, but keep the pattern in mind: @JoinTable on the owning side names the join table and both foreign key columns; the inverse side, if you need to navigate backward from Tag to its Tasks, uses @ManyToMany(mappedBy = "tags") the same way @OneToMany does above.

2. Lazy Loading & the N+1 Problem

Every JPA association has a fetch type that controls when the related data is actually loaded from the database. Get this wrong and you'll either crash with an exception outside a valid session, or silently fire hundreds of unnecessary queries — the N+1 problem is one of the most common performance bugs in any JPA-based application, and it's easy to introduce without noticing.

LAZY vs. EAGER

Collections (@OneToMany, @ManyToMany) default to FetchType.LAZY: the related rows aren't queried until you actually call a getter like project.getTasks(). Single-valued associations (@ManyToOne, @OneToOne) default to FetchType.EAGER, loading immediately with the owning entity — which is why, in the Task entity above, we explicitly override it to FetchType.LAZY rather than accept the default.

LazyInitializationException

A lazy association is loaded through a proxy that needs an open Hibernate session to resolve. If you return an entity from your service, close the session (as Spring does at the end of a @Transactional method), and only then touch task.getProject().getName() — say, while serializing a JSON response — you'll hit a LazyInitializationException. The fix isn't to make everything EAGER; it's to fetch what you need while the session is still open, inside the service method.

The N+1 query problem

Suppose you list every task for a project and print each task's project name:

List<Task> tasks = taskRepository.findAll();   // 1 query

for (Task task : tasks) {
    System.out.println(task.getProject().getName());  // N more queries!
}
// Total: 1 query to fetch tasks, plus one *additional* query per task
// to lazily resolve its Project -- N+1 queries for N tasks.

For 100 tasks, that's 101 round trips to the database instead of one or two — and it's invisible in code review because each individual line looks harmless. It shows up as a slow endpoint under load, and in the SQL log as a burst of nearly identical SELECT ... FROM projects WHERE id = ? statements.

Fixing it: JOIN FETCH and @EntityGraph

Both techniques tell Hibernate to pull the association in the same query instead of a follow-up one. JOIN FETCH in a JPQL query is explicit and easy to read:

public interface TaskRepository extends JpaRepository<Task, Long> {

    @Query("SELECT t FROM Task t JOIN FETCH t.project WHERE t.project.id = :projectId")
    List<Task> findByProjectIdWithProject(@Param("projectId") Long projectId);
}

@EntityGraph achieves the same result declaratively, without hand-writing JPQL, and reads well on a derived query method:

public interface TaskRepository extends JpaRepository<Task, Long> {

    @EntityGraph(attributePaths = "project")
    List<Task> findByProjectId(Long projectId);
}

Either way, one query comes back with tasks and their projects already populated — touching task.getProject().getName() afterward costs nothing extra.

3. Transactions with @Transactional

A transaction is a unit of work that either commits completely or rolls back completely — no partial writes. JPA and Hibernate already wrap each individual repository call in a short transaction, but as soon as an operation spans more than one write, you need to draw that boundary yourself.

Where @Transactional belongs

Put @Transactional on service-layer methods, not on repository methods (Spring Data already manages transactions for individual repository calls) and not on controllers (an HTTP-layer concern has no business defining a database transaction boundary). The service method is where you can see the whole multi-step operation — moving a task between projects, say — and that's the natural place to say "all of this succeeds together, or none of it does."

package com.codeverse.week05.task;

import com.codeverse.week05.project.Project;
import com.codeverse.week05.project.ProjectRepository;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class TaskService {

    private final TaskRepository taskRepository;
    private final ProjectRepository projectRepository;

    public TaskService(TaskRepository taskRepository, ProjectRepository projectRepository) {
        this.taskRepository = taskRepository;
        this.projectRepository = projectRepository;
    }

    @Transactional(readOnly = true)
    public List<Task> tasksForProject(Long projectId) {
        return taskRepository.findByProjectId(projectId);
    }

    @Transactional
    public Task moveTaskToProject(Long taskId, Long newProjectId) {
        Task task = taskRepository.findById(taskId)
            .orElseThrow(() -> new TaskNotFoundException(taskId));
        Project newProject = projectRepository.findById(newProjectId)
            .orElseThrow(() -> new ProjectNotFoundException(newProjectId));

        task.setProject(newProject);
        // No explicit save() call needed: within an open transaction,
        // Hibernate tracks this managed entity and flushes the UPDATE
        // automatically at commit ("dirty checking").
        return task;
    }
}

readOnly = true

@Transactional(readOnly = true) on a pure query method is a hint to Hibernate that it can skip dirty-checking overhead and, depending on the driver, route to a read replica — a small, free optimization for methods that never write.

Rollback behavior

By default, Spring rolls back a transaction automatically when the method throws an unchecked exception (any RuntimeException or Error) — which is why TaskNotFoundException above should be a RuntimeException, not a checked one. Checked exceptions do not trigger a rollback unless you explicitly declare @Transactional(rollbackFor = SomeCheckedException.class), a frequent source of "the error was handled, but the bad data still committed" bugs.

4. Schema Migrations with Flyway

Week 4 likely relied on spring.jpa.hibernate.ddl-auto=update to let Hibernate generate and adjust tables from your entities automatically. It's fast to start with — and genuinely dangerous the moment more than one person, or more than one environment, is involved.

Why ddl-auto=update doesn't scale to a real project

update inspects your entities and tries to reconcile the live schema to match, but it has no concept of history: it can't reliably rename a column (it'll add a new one and leave the old one behind), it can silently diverge between your machine and a teammate's, and it has no safe way to run a data backfill alongside a structural change. In production, the account with a schema-altering role is usually not one you want your running application to hold at all.

Versioned migration files

Flyway replaces "let Hibernate guess" with plain, ordered SQL files under src/main/resources/db/migration, each one a permanent, numbered record of a schema change:

src/main/resources/db/migration/
├── V1__create_tasks_table.sql
├── V2__create_projects_table.sql
└── V3__add_project_id_to_tasks.sql

The naming convention matters: V<version>__<description>.sql (two underscores). Flyway tracks which versions have already run in a flyway_schema_history table it creates for itself, and on every startup applies any migration files with a higher version number than the last one it recorded — in order, exactly once, on every environment.

CREATE TABLE tasks (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    completed BOOLEAN NOT NULL DEFAULT FALSE
);

CREATE TABLE projects (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    name VARCHAR(255) NOT NULL
);

ALTER TABLE tasks
    ADD COLUMN project_id BIGINT;

ALTER TABLE tasks
    ADD CONSTRAINT fk_tasks_project
    FOREIGN KEY (project_id) REFERENCES projects (id);

With Flyway on the classpath (spring-boot-starter-jdbc plus the flyway-core dependency), switch ddl-auto to a mode that only validates rather than mutates the schema, and let Flyway own every structural change from here on:

spring.jpa.hibernate.ddl-auto=validate
spring.flyway.enabled=true

validate still checks that your entity mappings match the real schema at startup and fails fast if they've drifted — you get Hibernate's safety net without handing it write access to your table definitions.

5. Hands-on Exercise

6. Knowledge Check

Four quick questions. Expand each to check your answer.