Hibernate ORM With Panache

1. Overview

Hibernate is one of the most popular ORM frameworks, offering a rich set of features that simplify seamless access to the database layer. In this tutorial, we’ll explore an extension to simplify the management of entities using the Panache library in Quarkus.

2. Quarkus Panache

Panache is a Quarkus-specific library that streamlines the development of the persistence layer using Hibernate. Similarly to Spring Data JPA, Panache helps us to handle most of the boilerplate code. Panache provides convenient methods for creating, updating, and deleting records, performing basic queries, and defining custom repositories to manage the database layer.

To get Panache up and running, we’ll first need to add the required dependencies, both for Panache itself and for our database driver. In this article, we’ll be using H2 as our database engine:

<!-- Hibernate ORM specific dependencies -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-orm-panache</artifactId>
</dependency>
<!-- JDBC driver dependencies -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-jdbc-h2</artifactId>
</dependency>

Additionally, we need to define the properties for our project:

quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1
quarkus.datasource.username=sa
quarkus.datasource.password=sa
quarkus.hibernate-orm.database.generation=drop-and-create
quarkus.hibernate-orm.log.sql=true

3. Creating Entities With PanacheEntity

PanacheEntity is a base class provided by Quarkus Panache that offers convenient methods for managing entities in our application. By extending PanacheEntity, the entities automatically inherit an id field along with a set of built-in methods to perform common operations such as findAll(), findById(), persist(), and delete().

Panache leverages the Active Record pattern through PanacheEntity, streamlining development for projects with simple domain models by reducing boilerplate and making code more expressive.

Let’s create an entity that maps to the articles table:

@Entity
public class Article extends PanacheEntity {
    public String title;
    public String content;
    public Article() {
    }
    public Article(String title, String content) {
        this.title = title;
        this.content = content;
    }
}

4. Performing CRUD Operations

Now that our Article entity is set up, let’s walk through how to handle the usual CRUD operations with the Panache API. We’ll start by creating new articles:

Article article = new Article("Quarkus Panache", "Content of the article");
article.persist();

Next, we can execute the read operations to retrieve the data from the database:

// getting a list of all Article entities
List<Article> allArticles = Article.listAll();
// finding a specific article by ID
article = Article.findById(articleId);
// finding a specific article by ID via an Optional
Optional<Article> optional = Article.findByIdOptional(articleId);
article = optional.orElseThrow(() -> new NotFoundException());

We can also fetch records and apply filters to get data based on specific fields:

List<Article> articles = Article.list("title", "Quarkus Panache");

Lastly, we can delete records from the database using the delete method:

article.delete();

5. Using PanacheRepository for Custom Logic

Similarly to Spring Data, we can also implement our own logic via custom repositories with PanacheRepository:

@ApplicationScoped
public class ArticleRepository implements PanacheRepository<Article> {
    public Article findByTitle(String title) {
        return find("title", title).firstResult();
    }
    public List<Article> findPublished() {
        return list("status", "Published");
    }
    public void deleteDrafts() {
        delete("status", "Draft");
    }
}

6. Testing Panache Entities

We can take advantage of the rich support from Quarkus to test our Panache entities with @QuarkusTest:

@QuarkusTest
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
public class ArticleTest {
    @Test
    @Transactional
    @Order(1)
    public void testCreateArticle() {
        Article article = new Article("Quarkus Panache", "Content of the article", "Published");
        article.persist();
        assertNotNull(article.id);
        assertEquals(1, Article.count());
    }
}

7. Best Practices

Now, let’s examine some best practices when using Quarkus Panache:

7.1. Retrieving Data Pattern

Use the Active Record pattern (extends PanacheEntity) when dealing with simple use cases to minimize the business logic. Use the Repository pattern (implements PanacheRepository<T>) for more complex scenarios – for example, to separate modules.

7.2. PanacheQuery

Use PanacheQuery<T> to implement pagination or sorting:

public List<Article> findRecentArticles() {
    return find("order by publishedAt desc").page(Page.ofSize(10)).list();
}

7.3. Use Projections

For better performance, we can use custom queries with projections to retrieve only the fields we need, rather than fetching entire entities:

public List<String> findAllTitles() {
    return find("select title from Article").list();
}

8. Conclusion

In this article, we explored the Panache extension in Quarkus and how it simplifies managing Hibernate entities. We looked at how Panache makes it easy to define entities and perform common operations like creating, reading, updating, and deleting records. With the support for the Active Record and Repository patterns, Panache helps reduce boilerplate code and keeps our persistence layer clean and efficient.

As always, the complete code is available over on GitHub.