DEV Community: Deborah Arku

Liquibase and Hibernate: Managing Your Database Schema the Right Way

Deborah Arku — Mon, 13 Jul 2026 09:34:45 +0000

What is Liquibase?

If you are building a Java application with Spring Boot, chances are your project is already connected to a relational database — PostgreSQL, MySQL, or similar. As that application grows, so does your database. New tables get added, columns get renamed, constraints get updated, and if your team isn't careful, keeping track of all these changes across different environments (development, testing, staging, production) becomes a nightmare.

Liquibase is a database schema change management tool. It helps teams track, version, and safely apply changes to database structures such as tables, columns, and constraints, across every environment.

Although Liquibase works across multiple languages and frameworks, it is especially popular in the Java and Spring Boot ecosystem, where it integrates cleanly into your existing project setup.

Instead of manually running SQL scripts and hoping each environment stays in sync, Liquibase lets you describe changes in files called changelogs, then automatically applies those changes in the right order while keeping a full history of what has been applied.

Think of it this way:

Your application code is version-controlled with Git.
Liquibase brings that same Git-like versioning to your database schema.

Key Features of Liquibase

Schema Versioning

Liquibase stores database changes as changesets inside a changelog file. Each changeset has a unique ID and an author, and Liquibase records which changesets have been applied to each database, giving you a clear, auditable history of every structural change ever made.

Changelogs can be written in multiple formats: XML, YAML, JSON, or plain SQL, so your team can use whatever format they're most comfortable with.

Rollback Capability

Made a mistake? Liquibase can roll back changes to a previous state based on a tag, a date and time, or a specific number of changesets — for example, dropping a table that was just created or removing a column that was just added. Rolling back restores the schema. For more complex operations, you can define custom rollback SQL, which is critical for making safe production changes with confidence.

Cross-Environment Consistency

The same changelog file is applied across development, testing, and production. Liquibase tracks which changesets were applied where, eliminating the classic "it works in dev but not in prod" problem caused by out-of-sync environments.

CI/CD Friendly

Liquibase integrates well into CI/CD pipelines, allowing database changes to be deployed automatically alongside application code. This means your schema changes go through the same review, testing, and deployment process as the rest of your codebase.

In short: Liquibase treats your database schema as code; versioned, reviewed, and deployed in a repeatable, automated way.

Use Cases of Liquibase

Managing schema changes in microservices — Each service has its own database; Liquibase ensures schema changes are tracked per service independently.
Keeping multiple environments in sync — Dev, staging, and prod all run the same changelog, so no one forgets to run that script in staging.
Safe production deployments — Rollback support gives teams the confidence to deploy schema changes without the fear of permanent breakage.
Team collaboration on DB changes — Changesets live in Git, so they can be reviewed in pull requests just like application code.

What is Hibernate?

Now that we understand how Liquibase manages database structure, let's talk about how Java applications actually talk to the database at runtime. That's where Hibernate comes in.

Hibernate is a Java ORM (Object-Relational Mapping) framework. It maps Java classes and objects to relational database tables and rows, letting developers work with familiar Java objects instead of writing raw SQL.

Think of it as a layer sitting between your application and the database:

Java Application
       ↓
  Hibernate ORM
       ↓
Database (PostgreSQL, MySQL, Oracle, etc.)

Without Hibernate, you'd be doing manual JDBC work: writing SQL, managing connections, and painstakingly mapping result sets to objects. Hibernate handles all of that for you automatically.

Key Features of Hibernate

ORM Capabilities

Hibernate maps Java classes to database tables and class fields to columns. It also handles relationships between entities — like one-to-many and many-to-many — using Java collections and annotations, meaning you rarely need to think in SQL terms.

Automatic CRUD

Hibernate provides built-in APIs for Create, Read, Update, and Delete operations (e.g., save(), find(), delete()) without needing to write SQL for each one. This significantly speeds up development and reduces boilerplate code.

Caching

Hibernate uses a first-level cache (per session) and an optional second-level cache (shared across sessions) to reduce the number of database hits and improve application performance.

Database Dialect Support

Hibernate supports multiple databases and uses dialects to generate database-specific SQL under the hood, while keeping your Java code completely database-agnostic. Switching from MySQL to PostgreSQL? Hibernate handles standard SQL translation seamlessly, although database-specific features will still require manual attention.

HQL and Criteria API

For more complex queries, Hibernate offers Hibernate Query Language (HQL) — an object-oriented query language similar to SQL — and a Criteria API for building queries programmatically in Java.

In short: Hibernate is used when you want to abstract away most SQL, work with Java objects, and build data-heavy applications quickly and cleanly.

How Hibernate and Liquibase Relate

Here's a key thing to understand: Hibernate and Liquibase are not competing tools. They solve completely different problems.

Aspect	Hibernate	Liquibase
Main purpose	ORM: map Java objects to tables, handle CRUD	Schema change management and versioning
Level	Application data access layer	DevOps / DB migration layer
Focus	How to read/write data at runtime	How the schema evolves over time
Typical output	Generated SQL for queries and inserts	Migration scripts applied as changesets
Versioning	No built-in schema versioning	Built-in schema versioning and rollback
File formats	Java classes, annotations	XML, YAML, JSON, SQL changelogs

A clean way to remember the difference:

Hibernate is about how your application talks to the database today. Liquibase is about how your database changes safely between today and tomorrow.

Seeing Them Side by Side

Let's make this concrete. Say you have a Student entity in your Spring Boot application. Here is how each tool represents the same concept:
Hibernate — the Java entity class:

@Entity
@Table(name = "students")
public class Student {

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

    @Column(name = "full_name", nullable = false)
    private String fullName;

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

    @Column(name = "department")
    private String department;
}

Liquibase — the changelog that creates the same table:

<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.0.xsd">

    <changeSet id="1" author="ama">
        <createTable tableName="students">
            <column name="id" type="BIGINT" autoIncrement="true">
                <constraints primaryKey="true" nullable="false"/>
            </column>
            <column name="full_name" type="VARCHAR(255)">
                <constraints nullable="false"/>
            </column>
            <column name="email" type="VARCHAR(255)">
                <constraints nullable="false" unique="true"/>
            </column>
            <column name="department" type="VARCHAR(255)"/>
        </createTable>
    </changeSet>

</databaseChangeLog>

Notice how they mirror each other; the same fields, constraints, and table name, but from completely different angles. The Hibernate entity tells your application how to work with student data. The Liquibase changelog tells your database how to create the students table in the first place, in a tracked and versioned way.

Why Not Just Use Hibernate for Schema Management?

This is a fair question. Hibernate actually has a built-in feature called hbm2ddl.auto that can create or update tables directly from your entity mappings. Many teams start out using this, and it works well early on.

But as projects mature, this approach runs into problems:

It gives you no rollback support if something goes wrong
It becomes risky in complex production databases with real data
There's no clear audit trail of what changed and when
Coordinating schema changes across multiple environments becomes messy

This is the gap Liquibase fills; providing explicit, version-controlled migrations instead of relying on "magic" schema generation.

How Teams Typically Evolve Their Approach

Early stages:
Teams often use Hibernate's auto DDL generation in development to quickly get tables created from entity classes. This is fine for prototyping and early development.

As the project matures:
There's a switch from hbm2ddl.auto (or spring.jpa.hibernate.ddl-auto in Spring Boot) to validate in production. This way, Hibernate simply checks that the database schema matches the entity mappings at startup, acting as a safety net to ensure Liquibase did its job correctly. Liquibase is introduced to define explicit migrations — changesets for creating tables, adding columns, updating constraints, etc.

Final setup:
Hibernate handles ORM and runtime data access. Liquibase handles schema changes in CI/CD, with rollback support and full version history. Both tools coexist, each doing what it does best.

Conclusion

Hibernate and Liquibase are complementary tools that together give you a complete picture of database management in Java applications. Hibernate makes it easy to work with your data as Java objects at runtime, while Liquibase ensures your database schema evolves safely, consistently, and traceably across every environment.

If you're working on a Spring Boot project, especially one heading toward production, understanding both tools isn't optional. It's what separates applications that scale gracefully from ones that break under pressure.

Understanding Controllers in Spring Boot: The Bridge Between Requests and Responses

Deborah Arku — Mon, 22 Jun 2026 11:00:00 +0000

What is a Controller?

In a Spring Boot web application, a controller is a Java class whose job is to receive HTTP requests (like GET /users), decide what to do with them, and send back an HTTP response.

It sits between the outside world (browser, mobile app, Postman, frontend) and your internal business logic (service layer, database, etc.).

A useful analogy: think of the controller as the receptionist of your application. It picks up the "phone call" (HTTP request), figures out which "department" (service) should handle it, and then returns the final "answer" (HTTP response) to the client.

What Do Controllers Actually Do?

Controllers in Spring Boot handle four responsibilities:

Map URLs to Java methods
Translate HTTP requests into method parameters
Call the business logic
Return HTTP responses

@Controller vs @RestController

Spring gives you two main annotations for building controllers, and choosing the right one matters.

@Controller

A traditional Spring MVC controller. It usually returns a view (e.g., an HTML page rendered with Thymeleaf).

Methods typically return a String (the view name) or a ModelAndView, and data is passed to the view via a Model.

For Example:

@Controller + method returning "user-list" 
→ Spring resolves this to user-list.html and renders HTML.

So the client doesn't receive JSON or raw data; they receive a fully rendered HTML page with the user list already built into it.

@RestController

A controller built specifically for REST APIs. It returns JSON or XML, not HTML.

@RestController is essentially @Controller + @ResponseBody applied automatically to every method. That means whatever your method returns (like a User object or a List<User>) is serialized directly into the HTTP response body.

In simple terms:

Use @Controller when building server-side rendered web pages.
Use @RestController when building REST APIs that return data (JSON/XML) to a frontend like React or a mobile app.

Example — @Controller (returns a view):

@Controller
public class UserViewController {

    @GetMapping("/users")
    public String listUsers(Model model) {
        model.addAttribute("users", userService.getAllUsers());
        return "user-list"; // resolves to user-list.html
    }
}

Example — @RestController (returns JSON):

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

    @GetMapping
    public List<User> getAllUsers() {
        return userService.getAllUsers(); // serialized directly to JSON
    }
}

Where Controllers Fit in MVC

Spring Boot follows the Model–View–Controller (MVC) architecture:

Model → Represents your data and business logic (JPA entities, DTOs, repositories, services)
View → Handles how data is presented. In classic Spring MVC, this could be Thymeleaf/HTML templates. In REST APIs, the "view" is often the JSON returned to the client.
Controller → Handles HTTP requests and responses, connecting the Model and the View

It helps to simplify this as:

Model = Data and rules. View = What the user sees. Controller = Coordinator between the user and the system.

The Three Core Purposes of a Controller

1. Routing and Handling Requests

Controllers define routes (endpoints) and attach them to Java methods using @RequestMapping on the class and method, or shortcut annotations like @GetMapping and @PostMapping.

This tells Spring: "When a request hits /api/users with method GET, call this particular Java method."

2. Interacting with the Service Layer

Controllers should stay thin. They:

Validate and unpack the incoming request (path variables, query parameters, JSON bodies)
Delegate to services (e.g., userService.createUser(user)), where the actual business logic lives
Handle high-level errors by catching exceptions and returning meaningful HTTP status codes

Controllers shouldn't contain heavy logic themselves. Instead, they call services or other components that implement the actual business rules. This separation makes your code testable, maintainable, and easier to reason about.

3. Returning Responses

Controllers craft the final HTTP response by choosing:

The status code (200 OK, 201 Created, 400 Bad Request, 404 Not Found, etc.)
The body (a JSON object, a list, or nothing)
Optional headers (like Location after creating a resource)

ResponseEntity gives you fine-grained control over all of this.

Key Controller Annotations

Class-Level Annotations

@Controller — marks a class as a Spring MVC controller that returns views
@RestController — marks a class as a REST controller; all methods write their return value directly to the HTTP response body

Mapping URLs: @RequestMapping

@RequestMapping can go on a class or a method.

On the class: sets a common base path, like /api/users
On methods: defines specific endpoints and/or HTTP methods, e.g. @RequestMapping(path = "/{id}", method = RequestMethod.GET)

Most modern Spring code prefers the more specific *Mapping annotations on methods (covered next) over writing this out manually.

HTTP Method Shortcuts

These annotations are shortcuts for @RequestMapping(method = ...):

Annotation	HTTP Method	Purpose	Idempotency
`@GetMapping`	GET	Read or fetch data	Yes
`@PostMapping`	POST	Create new resources	No
`@PutMapping`	PUT	Update or fully replace an existing resource	Yes
`@PatchMapping`	PATCH	Partially update a resource (e.g., only a user's email)	No
`@DeleteMapping`	DELETE	Delete a resource, usually by ID	Yes

Idempotent means calling the operation multiple times produces the same result as calling it once.

A typical CRUD REST controller looks like this:

GET    /items       → list all items
GET    /items/{id}  → get one item
POST   /items        → create new item
PUT    /items/{id}  → update/replace item
PATCH  /items/{id}  → partial update
DELETE /items/{id}  → delete item

Here's what that looks like in actual code:

@RestController
@RequestMapping("/items")
public class ItemController {

    private final ItemService itemService;

    public ItemController(ItemService itemService) {
        this.itemService = itemService;
    }

    @GetMapping
    public List<Item> getAllItems() {
        return itemService.findAll();
    }

    @GetMapping("/{id}")
    public ResponseEntity<Item> getItemById(@PathVariable Long id) {
        return itemService.findById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    public ResponseEntity<Item> createItem(@RequestBody ItemCreateRequest request) {
        Item created = itemService.create(request);
        return ResponseEntity.status(HttpStatus.CREATED).body(created);
    }

    @PutMapping("/{id}")
    public ResponseEntity<Item> updateItem(@PathVariable Long id, @RequestBody ItemUpdateRequest request) {
        Item updated = itemService.update(id, request);
        return ResponseEntity.ok(updated);
    }

    @PatchMapping("/{id}")
    public ResponseEntity<Item> partialUpdateItem(@PathVariable Long id, @RequestBody Map<String, Object> updates) {
        Item patched = itemService.partialUpdate(id, updates);
        return ResponseEntity.ok(patched);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteItem(@PathVariable Long id) {
        itemService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

Extracting Data: @PathVariable, @RequestParam, @RequestBody

@PathVariable
Reads data directly from the URL path.

Example: /users/5 → 5 is mapped to a method parameter like @PathVariable Long id. Common when working with a specific resource by ID.

@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
    return userService.findById(id);
}

@RequestParam
Reads query parameters from the URL.

Example: /users?role=ADMIN&active=true → role and active can be mapped with @RequestParam String role, @RequestParam boolean active. Good for optional filters, pagination, or sorting.

@GetMapping("/users")
public List<User> getUsers(
        @RequestParam String role,
        @RequestParam(defaultValue = "true") boolean active) {
    return userService.findByRoleAndStatus(role, active);
}

@RequestBody
Reads the HTTP request body (usually JSON) and maps it to a Java object (DTO).

Typical for POST/PUT/PATCH requests, where the client sends JSON like { "name": "Deborah", "email": "deborah@example.com" }. Spring (via Jackson) deserializes this JSON into a Java class when you annotate a parameter with @RequestBody.

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody UserCreateRequest request) {
    User newUser = userService.create(request);
    return ResponseEntity.status(HttpStatus.CREATED).body(newUser);
}

ResponseEntity: Precise Control Over Responses

ResponseEntity<T> represents the entire HTTP response, giving you control over:

Status code (200, 201, 204, 400, 404, 500, etc.)
Headers (like Location, custom headers, CORS-related headers)
Body (generic type T — could be an object, a list, or even Void)

Why this matters: for success cases, you can return ResponseEntity.ok(body) or ResponseEntity.status(HttpStatus.CREATED).body(body). For errors, you can return meaningful codes, like ResponseEntity.status(HttpStatus.NOT_FOUND).build().

@GetMapping("/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    Optional<User> user = userService.findById(id);

    if (user.isPresent()) {
        return ResponseEntity.ok(user.get()); // 200 OK with the user in the body
    } else {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).build(); // 404, no body
    }
}

This shows that controllers aren't just about returning data — they also communicate how an operation went, using proper HTTP semantics.

Conclusion

Controllers are the entry point to your Spring Boot application. They route requests, delegate work to the service layer, and shape the final response sent back to the client. Understanding the difference between @Controller and @RestController, knowing how to extract data with @PathVariable, @RequestParam, and @RequestBody, and using ResponseEntity for precise responses will give you a solid foundation for building robust backend APIs.

Once these concepts click, you'll start seeing every Spring Boot project through the lens of: where's the controller, what does it route, and what does it hand off?

Creating and Mapping Entities in JPA: Essential Annotations Explained

Deborah Arku — Mon, 16 Feb 2026 20:45:23 +0000

What is JPA?
JPA (Java Persistence API) is a Java standard that makes it easier to work with relational databases. Instead of writing complex SQL queries, JPA lets you map Java classes to database tables and manage data using simple Java code. In short, JPA acts as a bridge between your Java objects and database records.

Understanding Entities
Before we look further into JPA annotations, let's clarify what an entity is.

An **entity **represents a real-world object or concept that can be uniquely identified and stored in a database. If you remember your early lessons in Object-Oriented Programming (OOP), you learned that classes represent real-world objects. In JPA, we use classes to represent entities in the same way.

Here's how the mapping works:

*Entity *→ Java class
*Table *→ Physical storage of the entity in the database
*Column *→ Field (attribute/property) in the class
*Row *→ Individual instance of the entity

For example, Student can be an entity. To capture the characteristics of each student, the table will have several columns like name, gender, department, and email address. Each row in this table represents a different student.

What is Entity Mapping?
Entity mapping is the process of defining how your Java classes correspond to database tables. Using JPA annotations, we specify:

Which class represents a database table
Which field is the primary key
How fields map to columns
How entities relate to each other

These annotations tell JPA exactly how to translate between your Java objects and database records. Let's explore the most common JPA annotations.

Core JPA Annotations
@entity
This annotation declares that a class is not just an ordinary Java class, but an entity that should be mapped to a database table.

Example:

@Entity
public class Student {
    // fields, constructors, methods
}

@id
Every database table needs a primary key. A primary key is a unique value that distinguishes one record from another. The @id annotation marks a field as the primary key of the entity.

Example:

@Entity
public class Student {
    @Id
    private Long id;
    private String name;
    private String email;
}

@column
This annotation specifies the details of the column that a field maps to. While JPA automatically maps fields to columns with the same name, @column allows you to customize the column name, length, whether it can be null, and more.

Example:

@Entity
public class Student {
    @Id
    private Long id;

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

    @Column(name = "email_address", unique = true)
    private String email;
}

@Table
By default, JPA uses the class name as the table name. The @Table annotation lets you customize this mapping by explicitly specifying the table name, schema, or unique constraints. This is especially useful when your class name conflicts with database reserved words or when you need to follow specific database naming conventions.

Example:

@Entity
@Table(name = "students", schema = "university_db")
public class Student {
    @Id
    private Long id;
    private String name;
}

Relationship Annotations

In real applications, entities often have relationships with each other. JPA provides annotations to map these relationships.

@OneToOne
This annotation defines a one-to-one relationship between two entities. One instance of an entity is associated with exactly one instance of another entity.

Example: Each student has exactly one student profile.

@Entity
public class Student {
    @Id
    private Long id;
    private String name;

    @OneToOne
    @JoinColumn(name = "profile_id")
    private StudentProfile profile;
}

@Entity
public class StudentProfile {
    @Id
    private Long id;
    private String bio;
    private String photoUrl;
}

@OneToMany
This annotation defines a one-to-many relationship. One instance of an entity is associated with multiple instances of another entity.

Example: One department has many students.

@Entity
public class Department {
    @Id
    private Long id;
    private String name;

    @OneToMany(mappedBy = "department")
    private List<Student> students;
}

@Entity
public class Student {
    @Id
    private Long id;
    private String name;

    @ManyToOne
    @JoinColumn(name = "department_id")
    private Department department;
}

@ManyToOne
This is the inverse of @OneToMany. Multiple instances of an entity are associated with one instance of another entity.

Example: Many students belong to one department (shown in the example above).

@ManyToMany
This annotation defines a many-to-many relationship where multiple instances of one entity are associated with multiple instances of another entity.

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

@Entity
public class Student {
    @Id
    private Long id;
    private String name;

    @ManyToMany
    @JoinTable(
        name = "student_course",
        joinColumns = @JoinColumn(name = "student_id"),
        inverseJoinColumns = @JoinColumn(name = "course_id")
    )
    private List<Course> courses;
}

@Entity
public class Course {
    @Id
    private Long id;
    private String title;

    @ManyToMany(mappedBy = "courses")
    private List<Student> students;
}

Conclusion
In this article, we explored the essentials of entity mapping in JPA, including key annotations like @entity, @id, @column, and @Table, as well as relationship annotations such as @OneToOne, @OneToMany, @ManyToOne, and @ManyToMany. Understanding these concepts is crucial for effectively working with JPA and managing how your Java objects are stored in a relational database.

As you continue building your Java applications, these annotations will become second nature, allowing you to focus on your business logic rather than complex SQL queries.