Groovy / Gradle

Access a database with JPA and Hibernate

Learn how to access a database with JPA and Hibernate using the Micronaut framework.

Iván López, Sergio del Amo

On this guide

In this section

Getting Started

In this guide, we will create a Micronaut application written in Groovy.

In this guide, we will write a Micronaut application that exposes some REST endpoints and stores data in a database using JPA and Hibernate.

What you will need

To complete this guide, you will need the following:

Some time on your hands
A decent text editor or IDE (e.g. IntelliJ IDEA)
JDK 21 or greater installed with JAVA_HOME configured appropriately

Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Download and unzip the source

Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide --build=gradle --lang=groovy

Note	If you don’t specify the `--build` argument, Gradle with the Kotlin DSL is used as the build tool. If you don’t specify the `--lang` argument, Java is used as the language. If you don’t specify the `--test` argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

Setup IntelliJ IDEA to develop Micronaut Applications.

Data Source Dependencies

Add the following dependencies:

build.gradle

implementation("io.micronaut.sql:micronaut-hibernate-jpa") // 
implementation("io.micronaut.data:micronaut-data-tx-hibernate") // 
implementation("io.micronaut.sql:micronaut-jdbc-hikari") // 
runtimeOnly("com.h2database:h2") //

1	Configures Hibernate/JPA EntityManagerFactory beans.
2	Adds Micronaut Data Transaction Hibernate dependency.
3	Configures SQL DataSource instances using Hikari Connection Pool.
4	Add dependency to in-memory H2 Database.

Data Source Configuration

Define the data source in src/main/resources/application.properties.

src/main/resources/application.properties

datasources.default.password=${JDBC_PASSWORD:""}
datasources.default.url=${JDBC_URL:`jdbc:h2:mem:default;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE`}
datasources.default.username=${JDBC_USER:sa}
datasources.default.driver-class-name=${JDBC_DRIVER:org.h2.Driver}

Note

This way of defining the datasource properties means that we can externalize the configuration, for example for production environment, and also provide a default value for development. If the environment variables are not defined the Micronaut framework will use the default values.
Also keep in mind that it is necessary to escape the : in the connection URL using backticks `.

JPA configuration

Add the following snippet to src/main/resources/application.properties to configure JPA:

src/main/resources/application.properties

jpa.default.properties.hibernate.hbm2ddl.auto=update
jpa.default.properties.hibernate.show_sql=true

Domain

Create the domain entities:

groovy/src/main/groovy/example/micronaut/domain/Genre.groovy

package example.micronaut.domain

import com.fasterxml.jackson.annotation.JsonIgnore
import groovy.transform.CompileStatic
import io.micronaut.serde.annotation.Serdeable

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.Id
import jakarta.persistence.OneToMany
import jakarta.persistence.Table
import jakarta.validation.constraints.NotNull

import static jakarta.persistence.GenerationType.AUTO

@CompileStatic
@Serdeable
@Entity
@Table(name = 'genre')
class Genre {

    @Id
    @GeneratedValue(strategy = AUTO)
    Long id

    @NotNull
    @Column(name = 'name', nullable = false, unique = true)
    String name

    @JsonIgnore
    @OneToMany(mappedBy = 'genre')
    Set<Book> books = []

    Genre() {}

    Genre(@NotNull String name) {
        this.name = name
    }

    @Override
    String toString() {
        "Genre{id=$id, name='$name'}"
    }
}

The previous domain has a OneToMany relationship with the domain Book.

groovy/src/main/groovy/example/micronaut/domain/Book.groovy

package example.micronaut.domain

import groovy.transform.CompileStatic
import io.micronaut.serde.annotation.Serdeable

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.Id
import jakarta.persistence.ManyToOne
import jakarta.persistence.Table
import jakarta.validation.constraints.NotNull

import static jakarta.persistence.GenerationType.AUTO

@CompileStatic
@Serdeable
@Entity
@Table(name = 'book')
class Book {

    @Id
    @GeneratedValue(strategy = AUTO)
    Long id

    @NotNull
    @Column(name = 'name', nullable = false)
    String name

    @NotNull
    @Column(name = 'isbn', nullable = false)
    String isbn

    @ManyToOne
    Genre genre

    Book() {}

    Book(@NotNull String isbn,
         @NotNull String name,
         Genre genre) {
        this.isbn = isbn
        this.name = name
        this.genre = genre
    }

    @Override
    String toString() {
        "Book{id=$id, name='$name', isbn='$isbn', genre=$genre}"
    }
}

Application Configuration

Create an interface to encapsulate the application configuration settings:

groovy/src/main/groovy/example/micronaut/ApplicationConfiguration.groovy

package example.micronaut

interface ApplicationConfiguration {
    int getMax()
}

Like Spring Boot and Grails, in Micronaut applications you can create typesafe configuration by creating classes that are annotated with @ConfigurationProperties.

Create an ApplicationConfigurationProperties class:

groovy/src/main/groovy/example/micronaut/ApplicationConfigurationProperties.groovy

package example.micronaut

import groovy.transform.CompileStatic
import io.micronaut.context.annotation.ConfigurationProperties

@CompileStatic
@ConfigurationProperties('application') // 
class ApplicationConfigurationProperties implements ApplicationConfiguration {

    private final int DEFAULT_MAX = 10

    int max = DEFAULT_MAX
}

1	The `@ConfigurationProperties` annotation takes the configuration prefix.

You can override max if you add to your src/main/resources/application.properties:

src/main/resources/application.properties

application.max=50

Validation

Micronaut validation is built on the standard framework – JSR 380, also known as Bean Validation 2.0. Micronaut Validation has built-in support for validation of beans that are annotated with jakarta.validation annotations.

To use Micronaut Validation, you need the following dependencies:

build.gradle

compileOnly("io.micronaut.validation:micronaut-validation-processor")
implementation("io.micronaut.validation:micronaut-validation")

Alternatively, you can use Micronaut Hibernate Validator, which uses Hibernate Validator; a reference implementation of the validation API.

Repository Access

Next, create a repository interface to define the operations to access the database.

groovy/src/main/groovy/example/micronaut/GenreRepository.groovy

package example.micronaut

import example.micronaut.domain.Genre

import jakarta.validation.constraints.NotBlank
import jakarta.validation.constraints.NotNull

interface GenreRepository {

    Optional<Genre> findById(long id)

    Genre save(@NotBlank String name)

    Genre saveWithException(@NotBlank String name)

    void deleteById(long id)

    List<Genre> findAll(@NotNull SortingAndOrderArguments args)

    int update(long id, @NotBlank String name)
}

To mark the transaction demarcations, we use the Jakarta jakarta.transaction.Transactional annotation.

Write the implementation:

groovy/src/main/groovy/example/micronaut/GenreRepositoryImpl.groovy

package example.micronaut

import example.micronaut.domain.Genre
import io.micronaut.transaction.annotation.ReadOnly
import io.micronaut.transaction.annotation.Transactional
import jakarta.inject.Singleton

import jakarta.persistence.EntityManager
import jakarta.persistence.PersistenceException
import jakarta.persistence.TypedQuery
import jakarta.validation.constraints.NotBlank
import jakarta.validation.constraints.NotNull

@Singleton // 
class GenreRepositoryImpl implements GenreRepository {

    private static final List<String> VALID_PROPERTY_NAMES = ['id', 'name']

    private final EntityManager entityManager  // 
    private final ApplicationConfiguration applicationConfiguration

    GenreRepositoryImpl(EntityManager entityManager,
                        ApplicationConfiguration applicationConfiguration) { // 
        this.entityManager = entityManager
        this.applicationConfiguration = applicationConfiguration
    }

    @Override
    @ReadOnly  // 
    Optional<Genre> findById(long id) {
        Optional.ofNullable(entityManager.find(Genre, id))
    }

    @Override
    @Transactional // 
    Genre save(@NotBlank String name) {
        Genre genre = new Genre(name)
        entityManager.persist(genre)
        genre
    }

    @Override
    @Transactional // 
    void deleteById(long id) {
        findById(id).ifPresent(entityManager::remove)
    }

    @ReadOnly // 
    List<Genre> findAll(@NotNull SortingAndOrderArguments args) {
        String qlString = 'SELECT g FROM Genre as g'
        if (args.order && args.sort && VALID_PROPERTY_NAMES.contains(args.sort)) {
            qlString += ' ORDER BY g.' + args.sort + ' ' + args.order.toLowerCase()
        }
        TypedQuery<Genre> query = entityManager.createQuery(qlString, Genre)
        query.maxResults = args.max != null ? args.max : applicationConfiguration.max
        if (args.offset) {
            query.firstResult = args.offset
        }
        query.resultList
    }

    @Override
    @Transactional // 
    int update(long id, @NotBlank String name) {
        entityManager.createQuery('UPDATE Genre g SET name = :name where id = :id')
                .setParameter('name', name)
                .setParameter('id', id)
                .executeUpdate()
    }

    @Override // 
    @Transactional // 
    Genre saveWithException(@NotBlank String name) {
        save(name)
        throw new PersistenceException()
    }
}

1	Use `jakarta.inject.Singleton` to designate a class as a singleton.
2	Easily inject an `EntityManager`.
3	All database access needs to be wrapped inside a transaction. As the method only reads data from the database, annotate it with `@ReadOnly`.
4	This method modifies the database, thus it is annotated with `@Transactional`.

Note

When you use the Micronaut Data annotation processor, the framework maps the jakarta.transaction.Transactional annotation to io.micronaut.transaction.annotation.Transactional. In the previous code sample, we must use Micronaut @Transactional/@ReadOnly annotations, and we cannot use jakarta.transaction annotations since we don’t use Micronaut Data in this tutorial.

Controller

Create two classes to encapsulate Save and Update operations:

groovy/src/main/groovy/example/micronaut/GenreSaveCommand.groovy

package example.micronaut

import groovy.transform.CompileStatic
import io.micronaut.serde.annotation.Serdeable

import jakarta.validation.constraints.NotBlank

@CompileStatic
@Serdeable // 
class GenreSaveCommand {

    @NotBlank
    String name

    GenreSaveCommand(String name) {
        this.name = name
    }
}

1	Declare the `@Serdeable` annotation at the type level in your source code to allow the type to be serialized or deserialized.

groovy/src/main/groovy/example/micronaut/GenreUpdateCommand.groovy

package example.micronaut

import groovy.transform.CompileStatic
import io.micronaut.serde.annotation.Serdeable

import jakarta.validation.constraints.NotBlank

@CompileStatic
@Serdeable
class GenreUpdateCommand {

    long id

    @NotBlank
    String name

    GenreUpdateCommand(long id, String name) {
        this.id = id
        this.name = name
    }
}

Create a POJO to encapsulate Sorting and Pagination:

groovy/src/main/groovy/example/micronaut/SortingAndOrderArguments.groovy

package example.micronaut

import groovy.transform.CompileStatic
import io.micronaut.core.annotation.Nullable
import io.micronaut.serde.annotation.Serdeable

import jakarta.validation.constraints.Pattern
import jakarta.validation.constraints.Positive
import jakarta.validation.constraints.PositiveOrZero

@CompileStatic
@Serdeable
class SortingAndOrderArguments {

    @Nullable
    @PositiveOrZero // 
    Integer offset

    @Nullable
    @Positive // 
    Integer max

    @Nullable
    @Pattern(regexp = 'id|name')  // 
    String sort

    @Nullable
    @Pattern(regexp = 'asc|ASC|desc|DESC')  // 
    String order
}

1	Use `jakarta.validation.constraints` Constraints to ensure the incoming data matches your expectations.

Create GenreController, a controller which exposes a resource with the common CRUD operations:

groovy/src/main/groovy/example/micronaut/GenreController.groovy

package example.micronaut

import example.micronaut.domain.Genre
import groovy.transform.CompileStatic
import io.micronaut.http.HttpResponse
import io.micronaut.http.annotation.Body
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Delete
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Post
import io.micronaut.http.annotation.Put
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn

import jakarta.persistence.PersistenceException
import jakarta.validation.Valid

import static io.micronaut.http.HttpHeaders.LOCATION

@CompileStatic
@ExecuteOn(TaskExecutors.BLOCKING)  // 
@Controller('/genres')  // 
class GenreController {

    private final GenreRepository genreRepository

    GenreController(GenreRepository genreRepository) { // 
        this.genreRepository = genreRepository
    }

    @Get('/{id}') // 
    Genre show(Long id) {
        genreRepository
                .findById(id)
                .orElse(null) // 
    }

    @Put // 
    HttpResponse<?> update(@Body @Valid GenreUpdateCommand command) { // 
        int numberOfEntitiesUpdated = genreRepository.update(command.id, command.name)

        HttpResponse
                .noContent()
                .header(LOCATION, location(command.id).path) // 
    }

    @Get(value = '/list{?args*}') // 
    List<Genre> list(@Valid SortingAndOrderArguments args) {
        genreRepository.findAll(args)
    }

    @Post // 
    HttpResponse<Genre> save(@Body @Valid GenreSaveCommand cmd) {
        Genre genre = genreRepository.save(cmd.name)

        HttpResponse
                .created(genre)
                .headers(headers -> headers.location(location(genre.id)))
    }

    @Post('/ex') // 
    HttpResponse<Genre> saveExceptions(@Body @Valid GenreSaveCommand cmd) {
        try {
            Genre genre = genreRepository.saveWithException(cmd.name)
            HttpResponse
                    .created(genre)
                    .headers(headers -> headers.location(location(genre.id)))
        } catch(PersistenceException ignored) {
            HttpResponse.noContent()
        }
    }

    @Delete('/{id}') // 
    HttpResponse<?> delete(Long id) {
        genreRepository.deleteById(id)
        HttpResponse.noContent()
    }

    private URI location(Long id) {
        URI.create('/genres/' + id)
    }
}

1	It is critical that any blocking I/O operations (such as fetching the data from the database) are offloaded to a separate thread pool that does not block the Event loop.
2	The class is defined as a controller with the @Controller annotation mapped to the path `/genres`.
3	Constructor injection.
4	Maps a `GET` request to `/genres/{id}` which attempts to show a genre. This illustrates the use of a URL path variable.
5	Returning `null` when the genre doesn’t exist makes the Micronaut framework respond with 404 (not found).
6	Maps a `PUT` request to `/genres` which attempts to update a genre.
7	Add `@Valid` to any method parameter which requires validation. Use a POJO supplied as a JSON payload in the request to populate command.
8	It is easy to add custom headers to the response.
9	Maps a `GET` request to `/genres` which returns a list of genres. This mapping illustrates URL parameters being mapped to a single POJO.
10	Maps a `POST` request to `/genres` which attempts to save a genre.
11	Maps a `POST` request to `/ex` which generates an exception.
12	Maps a `DELETE` request to `/genres/{id}` which attempts to remove a genre. This illustrates the use of a URL path variable.

Writing Tests

Create a test to verify the CRUD operations:

groovy/src/test/groovy/example/micronaut/GenreControllerSpec.groovy

package example.micronaut

import example.micronaut.domain.Genre
import io.micronaut.core.type.Argument
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.client.BlockingHttpClient
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.http.client.exceptions.HttpClientResponseException
import io.micronaut.test.extensions.spock.annotation.MicronautTest
import jakarta.inject.Inject
import spock.lang.Specification

import static io.micronaut.http.HttpHeaders.LOCATION
import static io.micronaut.http.HttpStatus.BAD_REQUEST
import static io.micronaut.http.HttpStatus.CREATED
import static io.micronaut.http.HttpStatus.NOT_FOUND
import static io.micronaut.http.HttpStatus.NO_CONTENT

@MicronautTest // 
class GenreControllerSpec extends Specification {

    private BlockingHttpClient blockingClient

    @Inject
    @Client('/')
    HttpClient client // 

    void setup() {
        blockingClient = client.toBlocking()
    }

    void supplyAnInvalidOrderTriggersValidationFailure() {

        when:
        blockingClient.exchange(HttpRequest.GET('/genres/list?order=foo'))

        then:
        HttpClientResponseException e = thrown()
        e.response
        BAD_REQUEST == e.status
    }

    void testFindNonExistingGenreReturns404() {
        when:
        blockingClient.exchange(HttpRequest.GET('/genres/99'))

        then:
        HttpClientResponseException e = thrown()
        e.response
        NOT_FOUND == e.status
    }

    void testGenreCrudOperations() {

        given:
        List<Long> genreIds = []

        when:
        HttpRequest<?> request = HttpRequest.POST('/genres', new GenreSaveCommand('DevOps')) // 
        HttpResponse<?> response = blockingClient.exchange(request)
        genreIds << entityId(response)

        then:
        CREATED == response.status

        when:
        request = HttpRequest.POST('/genres', new GenreSaveCommand('Microservices')) // 
        response = blockingClient.exchange(request)

        then:
        CREATED == response.status

        when:
        Long id = entityId(response)
        genreIds << id
        request = HttpRequest.GET('/genres/' + id)

        Genre genre = blockingClient.retrieve(request, Genre) // 

        then:
        'Microservices' == genre.name

        when:
        request = HttpRequest.PUT('/genres', new GenreUpdateCommand(id, 'Micro-services'))
        response = blockingClient.exchange(request)  // 

        then:
        NO_CONTENT == response.status

        when:
        request = HttpRequest.GET('/genres/' + id)
        genre = blockingClient.retrieve(request, Genre)


        then:
        'Micro-services' == genre.name

        when:
        request = HttpRequest.GET('/genres/list')
        List<Genre> genres = blockingClient.retrieve(request, Argument.of(List, Genre))

        then:
        2 == genres.size()

        when:
        request = HttpRequest.POST('/genres/ex', new GenreSaveCommand('Microservices')) // 
        response = blockingClient.exchange(request)

        then:
        NO_CONTENT == response.status

        when:
        request = HttpRequest.GET('/genres/list')
        genres = blockingClient.retrieve(request, Argument.of(List, Genre))

        then:
        2 == genres.size()

        when:
        request = HttpRequest.GET('/genres/list?max=1')
        genres = blockingClient.retrieve(request, Argument.of(List, Genre))

        then:
        1 == genres.size()
        'DevOps' == genres[0].name

        when:
        request = HttpRequest.GET('/genres/list?max=1&order=desc&sort=name')
        genres = blockingClient.retrieve(request, Argument.of(List, Genre))

        then:
        1 == genres.size()
        'Micro-services' == genres[0].name

        when:
        request = HttpRequest.GET('/genres/list?max=1&offset=10')
        genres = blockingClient.retrieve(request, Argument.of(List, Genre))

        then:
        0 == genres.size()

        cleanup:
        for (Long genreId : genreIds) {
            request = HttpRequest.DELETE('/genres/' + genreId)
            response = blockingClient.exchange(request)
            assert NO_CONTENT == response.status
        }
    }

    private Long entityId(HttpResponse response) {
        String path = '/genres/'
        String value = response.header(LOCATION)
        if (value == null) {
            return null
        }

        int index = value.indexOf(path)
        if (index != -1) {
            return value.substring(index + path.length()) as long
        }

        null
    }
}

1	Annotate the class with `@MicronautTest` so the Micronaut framework will initialize the application context and the embedded server. More info.
2	Inject the `HttpClient` bean and point it to the embedded server.
3	Creating HTTP Requests is easy thanks to the Micronaut framework fluid API.
4	If you care just about the object in the response, use `retrieve`.
5	Sometimes, receiving just the object is not enough and you need information about the response. In this case, instead of `retrieve` you should use the `exchange` method.

Testing the Application

To run the tests:

./gradlew test

Then open build/reports/tests/test/index.html in a browser to see the results.

Running the Application

To run the application, use the ./gradlew run command, which starts the application on port 8080.

Using PostgreSQL

When running in production, you want to use a real database instead of using H2. Let’s explain how to use PostgreSQL.

After installing Docker, execute the following command to run a PostgreSQL container:

docker run -it --rm \
    -p 5432:5432 \
    -e POSTGRES_USER=dbuser \
    -e POSTGRES_PASSWORD=theSecretPassword \
    -e POSTGRES_DB=micronaut \
    postgres:11.5-alpine

Add PostgreSQL driver dependency:

build.gradle

runtimeOnly("org.postgresql:postgresql")

To use PostgreSQL, set up several environment variables which match those defined in application.properties:

export JDBC_URL=jdbc:postgresql://localhost:5432/micronaut
export JDBC_USER=dbuser
export JDBC_PASSWORD=theSecretPassword
export JDBC_DRIVER=org.postgresql.Driver

Run the application again. If you look at the output you can see that the application uses PostgreSQL:

..
...
08:40:02.746 [main] INFO  org.hibernate.dialect.Dialect - HHH000400: Using dialect: org.hibernate.dialect.PostgreSQL10Dialect
....

Connect to your PostgreSQL database, and you will see both genre and book tables.

Save one genre, and your genre table will now contain an entry.

curl -X "POST" "http://localhost:8080/genres" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{ "name": "music" }'

Next Steps

Read more about the Configurations for Data Access section in the Micronaut documentation.

Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.

License

Note	All guides are released with an Apache License 2.0 for the code and a Creative Commons Attribution 4.0 license for the writing and media (images).