DEV Community

Cover image for Hibernate From Scratch: Understanding JPA, Entities, Repositories & Spring Boot
Wandana Maddumage
Wandana Maddumage

Posted on Edited on

Hibernate From Scratch: Understanding JPA, Entities, Repositories & Spring Boot

  • A beginner-friendly guide to understanding how Java applications communicate with databases using Hibernate and Spring Data JPA.

Introduction

When building a backend application, one of the most important responsibilities is managing data. Applications need to store information, retrieve records, update existing data, and delete records when necessary.

Traditionally, developers used SQL queries and JDBC (Java Database Connectivity) to communicate directly with relational databases.

Although JDBC provides powerful database access, writing SQL queries and manually mapping database records to Java objects can become repetitive, especially in large applications.

This is where JPA, Hibernate, and Spring Data JPA come into play.

These technologies simplify database operations by allowing developers to work with Java objects instead of writing SQL queries for every database operation.

In this article, we'll explore these concepts from scratch and understand how they work together in a Spring Boot application.

1. Understanding the Fundamentals

Before writing code, let's understand three important concepts.

What is ORM?

ORM stands for Object-Relational Mapping.

It is a technique that maps Java objects to relational database tables.

For example, imagine an application that manages users.

In Java, we might represent a user using a class:

public class User {
    private Long id;
    private String name;
    private String email;
}
Enter fullscreen mode Exit fullscreen mode

In a relational database, the same information might be stored in a table:

users

id name email
1 John john@example.com
2 Sarah sarah@example.com

ORM allows us to connect these two representations.

Instead of manually converting database rows into Java objects, an ORM framework handles much of that work.

What is JPA?

JPA stands for Java Persistence API, now officially known as Jakarta Persistence.

JPA is a specification that defines how Java applications should manage relational data.

It provides standard annotations and interfaces for:

  • Mapping Java classes to database tables.
  • Mapping object properties to database columns.
  • Managing entity relationships.
  • Persisting and retrieving data.
  • Managing entity lifecycle operations.

An important thing to understand is that JPA is not an implementation. It defines the rules and standards that persistence providers must follow.

What is Hibernate?

Hibernate is an ORM framework and one of the most widely used implementations of the JPA specification.

It provides the actual functionality behind many JPA operations.

For example, when we use:

userRepository.save(user);
Enter fullscreen mode Exit fullscreen mode

Hibernate can generate the appropriate SQL statement and execute it against the database.

Hibernate handles tasks such as:

  • Generating SQL queries.
  • Mapping database records to Java objects.
  • Managing entity states.
  • Tracking changes to entities.
  • Handling database relationships.
  • Managing persistence contexts.

In simple terms:

  • JPA defines the standard.
  • Hibernate implements the standard.
  • Spring Data JPA simplifies database access through repository abstractions.

2. How Spring Boot, JPA, Hibernate, and Spring Data JPA Work Together

These technologies are often used together in Spring Boot applications.

Let's understand their relationship.

        Spring Boot Application
                 |
                 v
          Spring Data JPA
                 |
                 v
              JPA API
                 |
                 v
             Hibernate
                 |
                 v
           JDBC Driver
                 |
                 v
          Relational Database
          (PostgreSQL / MySQL)
Enter fullscreen mode Exit fullscreen mode

Each layer has a specific responsibility.

Spring Boot

Provides application configuration and integrates the persistence technologies.

Spring Data JPA

Provides repository interfaces and reduces the amount of database-access code developers need to write.

JPA

Defines the persistence standards and annotations.

Hibernate

Implements JPA and performs the actual ORM operations.

JDBC Driver

Allows Java applications to communicate with the database.

Database

Stores the actual application data.

Understanding this architecture makes it easier to identify which technology is responsible for each operation.

3. Setting Up a Spring Boot Project

Let's create a simple Spring Boot application that uses Hibernate and PostgreSQL.

When creating a project using Spring Initializr, include these dependencies:

  • Spring Web
  • Spring Data JPA
  • PostgreSQL Driver
  • Validation

Spring Boot automatically configures Hibernate as the default JPA provider when the JPA starter is included, unless another provider is configured.

A simplified project structure might look like this:

src/main/java/com/example/demo/
│
├── controller/
│   └── UserController.java
│
├── service/
│   └── UserService.java
│
├── repository/
│   └── UserRepository.java
│
├── entity/
│   └── User.java
│
└── DemoApplication.java
Enter fullscreen mode Exit fullscreen mode

Each package has a specific responsibility:

  • entity: Defines database-mapped Java objects.
  • repository: Handles database access.
  • service: Contains business logic.
  • controller: Handles HTTP requests and responses.

This separation makes applications easier to maintain and extend.

4. Understanding Entities in JPA

An entity is a Java class that represents a database table.

Hibernate uses entity metadata to understand how Java objects should be mapped to database records.

Let's create a User entity.

package com.example.demo.entity;

import jakarta.persistence.*;
import java.time.LocalDateTime;

@Entity
@Table(name = "users")
public class User {

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

    @Column(nullable = false, length = 100)
    private String name;

    @Column(nullable = false, unique = true)
    private String email;

    @Column(name = "created_at")
    private LocalDateTime createdAt;

    public User() {
    }

    // Getters and setters
}
Enter fullscreen mode Exit fullscreen mode

Let's understand the important annotations.

@entity

Marks a Java class as a JPA entity.

Hibernate recognizes this class as something that should be persisted in the database.

@Table

Specifies the database table associated with the entity.

@Table(name = "users")
Enter fullscreen mode Exit fullscreen mode

Without this annotation, JPA derives the table name from the entity name.

@id

Defines the primary key of the entity.

Every entity must have an identifier.

@GeneratedValue

Specifies how the primary key should be generated.

For example:

@GeneratedValue(strategy = GenerationType.IDENTITY)
Enter fullscreen mode Exit fullscreen mode

Common generation strategies include:

  • IDENTITY: Relies on database-generated identity values.
  • SEQUENCE: Uses a database sequence.
  • TABLE: Uses a separate database table to generate identifiers.
  • AUTO: Allows the persistence provider to choose an appropriate strategy.

The best choice depends on the database and application requirements.

@column

Customizes how a Java field maps to a database column.

For example:

@Column(nullable = false, unique = true)
private String email;
Enter fullscreen mode Exit fullscreen mode

This indicates that the column should not accept null values and should contain unique values.

Important: JPA annotations describe mapping and schema-generation metadata. They do not replace proper database constraints and migrations in production applications.

5. Understanding Entity Relationships

Real-world applications rarely contain independent tables.

For example, an e-commerce application might have:

  • Users
  • Orders
  • Products
  • Payments

These tables need relationships to represent how data is connected.

JPA provides four primary relationship annotations.

@OneToOne

Represents a relationship where one record is associated with one other record.

Example: One user has one profile.

@OneToOne
@JoinColumn(name = "profile_id")
private Profile profile;
Enter fullscreen mode Exit fullscreen mode

@OneToMany

Represents a relationship where one record can be associated with multiple records.

Example: One user can have multiple orders.

@OneToMany(mappedBy = "user")
private List<Order> orders;
Enter fullscreen mode Exit fullscreen mode

@ManyToOne

Represents multiple records associated with one record.

Example: Multiple orders can belong to one user.

@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "user_id")
private User user;
Enter fullscreen mode Exit fullscreen mode

@ManyToMany

Represents a relationship where multiple records can be associated with multiple other records.

Example: Students can enroll in multiple courses, and each course can have multiple students.

@ManyToMany
@JoinTable(
    name = "student_courses",
    joinColumns = @JoinColumn(name = "student_id"),
    inverseJoinColumns = @JoinColumn(name = "course_id")
)
private Set<Course> courses;
Enter fullscreen mode Exit fullscreen mode

Understanding relationships is essential when designing a relational database using JPA.

6. What Are Repositories in Spring Data JPA?

After defining entities, we need a way to perform database operations.

This is where Spring Data JPA repositories become useful.

A repository is an abstraction that provides methods for interacting with the database.

Instead of manually writing SQL queries for basic operations, we can extend an existing Spring Data interface.

Let's create a UserRepository.

package com.example.demo.repository;

import com.example.demo.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository
        extends JpaRepository<User, Long> {

}
Enter fullscreen mode Exit fullscreen mode

That's it!

We haven't written any implementation code.

Spring Data JPA automatically provides the implementation at runtime.

By extending JpaRepository, we get access to several useful methods.

Method Purpose
save() Insert or update an entity
findById() Find an entity by its ID
findAll() Retrieve all entities
existsById() Check whether an entity exists
deleteById() Delete an entity by ID
count() Count available records

For example:

userRepository.findAll();
Enter fullscreen mode Exit fullscreen mode

Retrieves all users.

userRepository.findById(1L);
Enter fullscreen mode Exit fullscreen mode

Retrieves a user with ID 1.

userRepository.deleteById(1L);
Enter fullscreen mode Exit fullscreen mode

Deletes the user with ID 1.

Spring Data JPA generates the required database-access implementation behind these methods.

Custom Query Methods

One of the most useful features of Spring Data JPA is query method derivation.

We can define methods based on the properties of an entity.

For example:

public interface UserRepository
        extends JpaRepository<User, Long> {

    Optional<User> findByEmail(String email);

    List<User> findByName(String name);

    boolean existsByEmail(String email);
}
Enter fullscreen mode Exit fullscreen mode

Spring Data JPA analyzes these method names and generates the corresponding queries.

We can also write custom JPQL queries using @Query.

@Query("SELECT u FROM User u WHERE u.email = :email")
Optional<User> findUserByEmail(
    @Param("email") String email
);
Enter fullscreen mode Exit fullscreen mode

JPQL operates on entity classes and their properties rather than directly referencing database table and column names.

7. Understanding the Service Layer

In a properly structured Spring Boot application, controllers should not directly contain database operations.

Instead, we introduce a service layer to manage business logic.

Let's create a UserService.

package com.example.demo.service;

import com.example.demo.entity.User;
import com.example.demo.repository.UserRepository;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class UserService {

    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public User createUser(User user) {
        return userRepository.save(user);
    }

    public List<User> getAllUsers() {
        return userRepository.findAll();
    }
}
Enter fullscreen mode Exit fullscreen mode

Why use a service layer?

The service layer provides a place to implement:

  • Business rules.
  • Validation beyond basic input constraints.
  • Transaction management.
  • Coordination between multiple repositories.
  • Application-specific logic.

For example, before creating a user, we might check whether the email address is already registered.

This keeps the controller focused on handling HTTP requests rather than implementing business rules.

8. Connecting the Application to PostgreSQL

Now we need to configure the database connection.

In Spring Boot, database configuration is commonly defined in:

application.yml

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/demo_db
    username: postgres
    password: your_password
    driver-class-name: org.postgresql.Driver

  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: true
    properties:
      hibernate:
        format_sql: true
Enter fullscreen mode Exit fullscreen mode

Let's understand the configuration.

datasource.url

Specifies the database connection URL.

username and password

Provide database authentication credentials.

ddl-auto

Controls Hibernate's automatic database schema handling.

Common options include:

Value Description
create Creates the schema and may drop existing tables
create-drop Creates the schema and drops it when the session factory closes
update Attempts to update the schema
validate Checks whether the schema matches the entity mappings
none Disables automatic schema management

For production applications, using validate or none alongside a database migration tool such as Flyway or Liquibase is generally a safer approach.

Avoid relying on ddl-auto=update as your production database migration strategy.

9. Understanding the Entity Lifecycle

One of the most important Hibernate concepts is the entity lifecycle.

Hibernate manages entities through different states.

There are four commonly discussed states:

1. Transient

An object is transient when it has been created but is not associated with a persistence context.

User user = new User();
user.setName("John");
user.setEmail("john@example.com");
Enter fullscreen mode Exit fullscreen mode

At this point, the object exists only in application memory.

2. Managed (Persistent)

An entity becomes managed when it is associated with an active persistence context.

For example:

entityManager.persist(user);
Enter fullscreen mode Exit fullscreen mode

Hibernate starts tracking the entity.

Changes made to a managed entity can automatically be synchronized with the database.

3. Detached

An entity becomes detached when it is no longer associated with its persistence context.

For example, after the persistence context is closed, previously managed entities become detached.

Changes to detached objects are not automatically synchronized with the database.

4. Removed

An entity enters the removed state when it is scheduled for deletion.

entityManager.remove(user);
Enter fullscreen mode Exit fullscreen mode

The actual database deletion happens when the persistence context is flushed.

Understanding these states helps explain why Hibernate sometimes executes SQL statements even when we haven't explicitly called a save method.

10. What Is a Persistence Context?

A persistence context is an important part of JPA and Hibernate.

Think of it as an environment that manages entity instances during their lifecycle.

It maintains a collection of managed entities and tracks changes made to them.

For example:

@Transactional
public void updateUser(Long id) {

    User user = userRepository.findById(id)
        .orElseThrow();

    user.setName("Updated Name");
}
Enter fullscreen mode Exit fullscreen mode

Notice something interesting.

We didn't call:

userRepository.save(user);
Enter fullscreen mode Exit fullscreen mode

Yet the updated name can still be persisted.

Why?

Because the entity is managed by the persistence context.

Hibernate detects the changes and synchronizes them with the database during transaction flushing. This mechanism is called dirty checking.

This is one of Hibernate's most powerful features.

11. Understanding Transactions in Spring Boot

A database transaction is a group of operations treated as one logical unit.

Transactions help maintain data consistency.

Spring provides the @Transactional annotation to manage transactions.

Example:

@Transactional
public void transferMoney(
        Long fromAccountId,
        Long toAccountId,
        BigDecimal amount) {

    Account from = accountRepository
        .findById(fromAccountId)
        .orElseThrow();

    Account to = accountRepository
        .findById(toAccountId)
        .orElseThrow();

    from.setBalance(from.getBalance().subtract(amount));

    to.setBalance(to.getBalance().add(amount));
}
Enter fullscreen mode Exit fullscreen mode

Both updates should succeed together.

If an applicable unchecked exception occurs, Spring normally rolls back the transaction.

This prevents a situation where money is deducted from one account but not added to the other.

Transactions are particularly important when multiple database operations depend on each other.

12. Understanding Lazy and Eager Loading

When working with entity relationships, Hibernate needs to determine when related data should be retrieved.

JPA provides two common fetching strategies.

Lazy Loading

Related data is retrieved only when it is accessed.

@OneToMany(
    mappedBy = "user",
    fetch = FetchType.LAZY
)
private List<Order> orders;
Enter fullscreen mode Exit fullscreen mode

Eager Loading

Related data is retrieved eagerly as part of loading the entity, although the exact SQL strategy is provider-dependent.

@ManyToOne(fetch = FetchType.EAGER)
private User user;
Enter fullscreen mode Exit fullscreen mode

Lazy loading is generally a good default for collections because it avoids unnecessarily loading large amounts of data.

However, it can introduce the N+1 query problem.

For example, retrieving 100 orders and then accessing each order's user might result in one query to retrieve the orders and additional queries to retrieve users.

Possible solutions include:

  • JPQL JOIN FETCH.
  • Entity graphs.
  • DTO projections.
  • Batch fetching.

Understanding fetching strategies is important for building efficient applications.

13. Putting Everything Together: A Simple REST API

Now let's connect everything.

We'll create a REST controller that exposes user-related endpoints.

package com.example.demo.controller;

import com.example.demo.entity.User;
import com.example.demo.service.UserService;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userService.createUser(user);
    }

    @GetMapping
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }
}
Enter fullscreen mode Exit fullscreen mode

We now have two basic endpoints.

HTTP Method Endpoint Description
POST /api/users Create a user
GET /api/users Retrieve all users

The complete request flow looks like this:

       Client Request
             |
             v
       UserController
             |
             v
        UserService
             |
             v
       UserRepository
             |
             v
          Hibernate
             |
             v
         PostgreSQL
Enter fullscreen mode Exit fullscreen mode

When a client sends a request to create a user:

  1. The controller receives the HTTP request.
  2. The service handles the application logic.
  3. The repository executes the persistence operation.
  4. Hibernate translates the operation into SQL.
  5. The JDBC driver communicates with PostgreSQL.
  6. The database stores the record.
  7. The result is returned through the application layers.

This is the basic architecture behind many Spring Boot applications.

Note: This example demonstrates the persistence flow. A production API should use request/response DTOs, validation, exception handling, and appropriate transaction boundaries rather than exposing JPA entities directly.

14. Common Mistakes Beginners Should Avoid

When starting with Hibernate and Spring Data JPA, there are several common mistakes worth understanding.

1. Confusing JPA with Hibernate

JPA is a specification, while Hibernate is an implementation. They are related but not interchangeable concepts.

2. Using entities directly in REST APIs

Returning entities directly can expose internal database structures and create serialization problems, particularly with bidirectional relationships.

Use DTOs instead.

3. Ignoring entity relationships

Incorrect relationship mappings can cause duplicate records, unexpected SQL queries, or data consistency problems.

4. Using EAGER fetching everywhere

Eager loading can retrieve unnecessary data and negatively affect application performance.

5. Ignoring transactions

Operations involving multiple database changes should have appropriate transaction boundaries.

6. Depending on Hibernate to manage production schemas

Use database migration tools such as Flyway or Liquibase to manage schema changes in a controlled and versioned manner.

Conclusion

Understanding Hibernate, JPA, and Spring Data JPA is an important step toward becoming a capable Spring Boot backend developer.

The key concepts to remember are:

  • ORM connects Java objects with relational database tables.
  • JPA defines the persistence specification.
  • Hibernate implements the JPA specification.
  • Spring Data JPA simplifies database access through repositories.
  • Entities represent database records.
  • Repositories provide database operations.
  • Services manage business logic.
  • Persistence contexts track managed entities.
  • Transactions help maintain data consistency.
  • Fetching strategies influence database performance.

Rather than memorizing annotations and methods, focus on understanding what happens behind the scenes when an application communicates with a database.

Once you understand how these components work together, building more complex backend systems becomes much easier.

The best way to learn Hibernate is to build something with it. Start with a simple CRUD application, introduce entity relationships, implement transactions, and gradually explore more advanced persistence concepts.

Happy coding! 🚀


#Java #SpringBoot #Hibernate #JPA #SpringDataJPA #BackendDevelopment #SoftwareEngineering

Top comments (0)