Table of Contents

Access a database with JPA and Hibernate Reactive

Learn how to use Hibernate Reactive with the Micronaut Framework.

Authors: Tim Yates, Roman Naglic

Micronaut Version: 4.6.3

1. Getting Started

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

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

2. What you will need

To complete this guide, you will need the following:

3. 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.

4. 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=kotlin
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.

4.1. Data Source configuration

Add the following dependencies:

build.gradle
implementation("io.micronaut.reactor:micronaut-reactor") (1)
implementation("io.micronaut.sql:micronaut-hibernate-reactive") (2)
implementation("io.vertx:vertx-mysql-client") (3)
1 Add a dependency to the Micronaut Framework Project Reactor support
2 Configures Hibernate Reactive/JPA beans.
3 Adds a dependency to the Vert.x MySQL client.

4.2. JPA configuration

Add the next snippet to src/main/resources/application.yml to configure JPA:

Since Micronaut Framework 4.0, to use YAML configuration, you have to add the YAML dependency.
src/main/resources/application.yml
jpa:
  default:
    reactive: true
    properties:
      hibernate:
        connection:
          db-type: mysql
        hbm2ddl:
          auto: create-drop
        show_sql: true

4.3. Domain

Create the domain entities:

src/main/kotlin/example/micronaut/domain/Genre.kt
package example.micronaut.domain

import io.micronaut.serde.annotation.Serdeable

import com.fasterxml.jackson.annotation.JsonIgnore
import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Table
import jakarta.persistence.Id
import jakarta.persistence.OneToMany

@Serdeable
@Entity
@Table(name = "genre")
class Genre(
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @Column(name = "id", nullable = false, updatable = false)
    val id: Long?,

    @Column(name = "name", nullable = false)
    var name: String
) {

    @JsonIgnore
    @OneToMany(mappedBy = "genre")
    var books: MutableSet<Book> = mutableSetOf()
}

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

src/main/kotlin/example/micronaut/domain/Book.kt
package example.micronaut.domain

import io.micronaut.serde.annotation.Serdeable

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Table
import jakarta.persistence.Id
import jakarta.persistence.ManyToOne

@Serdeable
@Entity
@Table(name = "book")
class Book(
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    var id: Long,

    @Column(name = "name", nullable = false)
    var name: String,

    @Column(name = "isbn", nullable = false)
    var isbn: String
) {
    @ManyToOne
    var genre: Genre? = null
}

4.4. Application Configuration

Create an interface to encapsulate the application configuration settings:

src/main/kotlin/example/micronaut/ApplicationConfiguration.kt
package example.micronaut

interface ApplicationConfiguration {
    val max: Int
}

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

Create a ApplicationConfigurationProperties class:

src/main/kotlin/example/micronaut/ApplicationConfigurationProperties.kt
package example.micronaut

import io.micronaut.context.annotation.ConfigurationProperties

@ConfigurationProperties("application") (1)
class ApplicationConfigurationProperties : ApplicationConfiguration {
    private val DEFAULT_MAX = 10
    override var max = DEFAULT_MAX
}
1 The @ConfigurationProperties annotation takes the configuration prefix.

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

src/main/resources/application.yml
application:
  max: 50

4.5. Repository Access

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

src/main/kotlin/example/micronaut/GenreRepository.kt
package example.micronaut

import example.micronaut.domain.Genre
import org.reactivestreams.Publisher
import jakarta.validation.constraints.NotBlank

interface GenreRepository {
    fun findById(id: Long): Publisher<Genre?>
    fun save(name: String): Publisher<Genre>
    fun saveWithException(@NotBlank name: String): Publisher<Genre?>
    fun deleteById(id: Long)
    fun findAll(args: SortingAndOrderArguments): Publisher<Genre?>
    fun update(id: Long, @NotBlank name: String?): Publisher<Int?>
}

And the implementation:

src/main/kotlin/example/micronaut/GenreRepositoryImpl.kt
package example.micronaut

import example.micronaut.domain.Genre
import jakarta.inject.Singleton
import org.hibernate.SessionFactory
import org.hibernate.reactive.stage.Stage
import org.reactivestreams.Publisher
import reactor.core.publisher.Flux
import reactor.core.publisher.Mono
import jakarta.persistence.PersistenceException


@Singleton (1)
open class GenreRepositoryImpl(
    val applicationConfiguration: ApplicationConfiguration, (2)
    sessionFactory: SessionFactory, (3)
) : GenreRepository {
    private val sessionFactory: Stage.SessionFactory
    private val VALID_PROPERTY_NAMES = arrayOf("id", "name")

    init {
        this.sessionFactory = sessionFactory.unwrap(Stage.SessionFactory::class.java)
    }

    override fun findById(id: Long): Publisher<Genre?> {
        return Mono.fromCompletionStage(sessionFactory.withTransaction { session -> (4)
            session.find(Genre::class.java, id)
        })
    }

    override fun save(name: String): Publisher<Genre> {
        return Mono.fromCompletionStage(sessionFactory.withTransaction { session ->
            val entity = Genre(id = null, name = name)
            session.persist(entity)
                .thenApply { entity }
        })
    }

    override fun update(id: Long, name: String?): Publisher<Int?> {
        return Mono.fromCompletionStage(sessionFactory.withTransaction { session ->
            session.createQuery<Long>("UPDATE Genre g SET name = :name where id = :id")
                .setParameter("name", name)
                .setParameter("id", id)
                .executeUpdate()
        })
    }

    override fun findAll(args: SortingAndOrderArguments): Publisher<Genre?> {
        val qlString: String = createQuery(args)
        return Mono.fromCompletionStage(sessionFactory.withSession { session ->
            val query = session.createQuery(
                qlString,
                Genre::class.java
            )
            query.maxResults = args.max ?: applicationConfiguration.max
            args.offset?.let { query.setFirstResult(it) }
            query.resultList
        })
            .flatMapMany { Flux.fromIterable(it) }
    }

    private fun createQuery(args: SortingAndOrderArguments): String {
        var qlString = "SELECT g FROM Genre as g"
        val order = args.order
        val sort = args.sort
        if (order != null && sort != null && VALID_PROPERTY_NAMES.contains(sort)) {
            qlString += " ORDER BY g." + sort + ' ' + order.lowercase()
        }
        return qlString
    }

    override fun deleteById(id: Long) {
        sessionFactory.withTransaction { session ->
            session.find(Genre::class.java, id).thenApply { entity ->
                session.remove(entity)
            }
        }
    }

    override fun saveWithException(name: String): Publisher<Genre?> {
        return Mono.fromCompletionStage(sessionFactory.withTransaction { session ->
            val entity = Genre(id = null, name = name)
            session.persist(entity)
                .thenApply<Genre> { throw PersistenceException() }
        })
    }
}
1 Use jakarta.inject.Singleton to designate a class as a singleton.
2 Inject the ApplicationConfiguration.
3 Inject the Hibernate SessionFactory.
4 Grab a transactional session from the SessionFactory to run our query.

4.6. Controller

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
kapt("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.

Create two classes to encapsulate Save and Update operations:

src/main/kotlin/example/micronaut/GenreSaveCommand.kt
package example.micronaut

import io.micronaut.serde.annotation.Serdeable

import jakarta.validation.constraints.NotBlank

@Serdeable (1)
class GenreSaveCommand(@field:NotBlank var name: String)
1 Declare the @Serdeable annotation at the type level in your source code to allow the type to be serialized or deserialized.
src/main/kotlin/example/micronaut/GenreUpdateCommand.kt
package example.micronaut

import io.micronaut.serde.annotation.Serdeable

import jakarta.validation.constraints.NotBlank

@Serdeable
class GenreUpdateCommand(var id: Long, @field:NotBlank var name: String?)

Create a POJO to encapsulate Sorting and Pagination:

src/main/kotlin/example/micronaut/SortingAndOrderArguments.kt
package example.micronaut

import io.micronaut.serde.annotation.Serdeable
import jakarta.validation.constraints.Pattern
import jakarta.validation.constraints.Positive
import jakarta.validation.constraints.PositiveOrZero

@Serdeable
data class SortingAndOrderArguments(
    @field:PositiveOrZero var offset:  Int? = null, (1)
    @field:Positive var max: Int? = null, (1)
    @field:Pattern(regexp = "id|name") var sort: String? = null, (1)
    @field:Pattern(regexp = "asc|ASC|desc|DESC") var order: String? = null (1)
)
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:

src/main/kotlin/example/micronaut/GenreController.kt
package example.micronaut

import example.micronaut.domain.Genre
import io.micronaut.core.async.annotation.SingleResult
import io.micronaut.http.*
import io.micronaut.http.annotation.*
import org.reactivestreams.Publisher
import reactor.core.publisher.Mono
import java.net.URI
import jakarta.persistence.PersistenceException
import jakarta.validation.Valid

@Controller("/genres")  (1)
open class GenreController(val genreRepository: GenreRepository) { (2)

    @Get("/{id}") (3)
    @SingleResult
    fun show(id: Long): Publisher<Genre?> {
        return genreRepository.findById(id) (4)
    }

    @Put (5)
    open fun update(@Valid @Body command: GenreUpdateCommand): Publisher<HttpResponse<*>> { // <6>(6)
        return Mono.from(genreRepository.update(command.id, command.name))
            .map {
                HttpResponse
                    .noContent<Any>()
                    .header(HttpHeaders.LOCATION, location(command.id).path)
            } (7)
    }

    private fun location(id: Long): URI {
        return URI.create("/genres/$id")
    }

    @Get(value = "/list{?args*}") (8)
    open fun list(@Valid args: SortingAndOrderArguments): Publisher<Genre?> {
        return genreRepository.findAll(args)
    }

    @Post (9)
    @SingleResult
    open fun save(@Valid @Body cmd: GenreSaveCommand): Publisher<HttpResponse<Genre>>? {
        return Mono.from(genreRepository.save(cmd.name))
            .map { genre ->
                HttpResponse
                    .created(genre)
                    .headers { headers ->
                        headers.location(location(genre.id!!))
                    }
            }
    }

    @Post("/ex") (10)
    @SingleResult
    open fun saveExceptions(@Valid @Body cmd: GenreSaveCommand): Publisher<MutableHttpResponse<Genre?>> {
        return Mono.from(genreRepository.saveWithException(cmd.name))
            .map { genre: Genre? ->
                HttpResponse
                    .created(genre)
                    .headers { headers: MutableHttpHeaders ->
                        headers.location(
                            location(
                                genre!!.id!!
                            )
                        )
                    }
            }
            .onErrorReturn(PersistenceException::class.java, HttpResponse.noContent())
    }

    @Delete("/{id}") (11)
    @Status(HttpStatus.NO_CONTENT) (12)
    fun delete(id: Long): HttpResponse<*> {
        genreRepository.deleteById(id)
        return HttpResponse.noContent<Any>()
    }
}
1 The class is defined as a controller with the @Controller annotation mapped to the path /genres.
2 Use constructor injection to inject a bean of type GenreRepository.
3 The @Get annotation maps the show method to an HTTP GET request on /{id}.
4 Returning an empty Publisher when the genre doesn’t exist makes the Micronaut framework respond with 404 (not found).
5 Maps a PUT request to /genres which attempts to update a genre.
6 Add @Valid to any method parameter which requires validation.
7 Add custom headers to the response.
8 Maps a GET request to /genres which returns a list of genres.
9 Maps a POST request to /genres which attempts to save a genre.
10 Maps a POST request to /ex which generates an exception.
11 The @Delete annotation maps the delete method to an HTTP Delete request on /genres/{id}.
12 You can return void in your controller’s method and specify the HTTP status code via the @Status annotation.

4.7. Writing Tests

Create a test to verify the CRUD operations:

src/test/kotlin/example/micronaut/GenreControllerTest.kt
package example.micronaut

import example.micronaut.domain.Genre
import io.micronaut.core.type.Argument
import io.micronaut.http.HttpHeaders
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.HttpStatus
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.junit5.annotation.MicronautTest
import org.junit.jupiter.api.Assertions
import org.junit.jupiter.api.BeforeEach
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.TestInstance

import jakarta.inject.Inject


@MicronautTest (1)
@TestInstance(TestInstance.Lifecycle.PER_CLASS) (2)
class GenreControllerTest {
    
    @Inject
    @field:Client("/")
    lateinit var httpClient: HttpClient (3)
    
    var blockingClient: BlockingHttpClient? = null

    @BeforeEach
    fun setup() {
        blockingClient = httpClient.toBlocking()
    }

    @Test
    fun supplyAnInvalidOrderTriggersValidationFailure() {
        val thrown = Assertions.assertThrows(HttpClientResponseException::class.java) {
            blockingClient!!.exchange<Any, Any>(HttpRequest.GET("/genres/list?order=foo"))
        }
        Assertions.assertNotNull(thrown.response)
        Assertions.assertEquals(HttpStatus.BAD_REQUEST, thrown.status)
    }

    @Test
    fun testFindNonExistingGenreReturns404() {
        val thrown = Assertions.assertThrows(HttpClientResponseException::class.java) {
            httpClient.toBlocking().exchange<Any, Any>(HttpRequest.GET("/genres/99"))
        }
        Assertions.assertNotNull(thrown.response)
        Assertions.assertEquals(HttpStatus.NOT_FOUND, thrown.status)
    }

    @Test
    fun testGenreCrudOperations() {
        val genreIds = mutableListOf<Long?>()
        var request: HttpRequest<*>? = HttpRequest.POST("/genres", GenreSaveCommand("DevOps")) (4)
        var response: HttpResponse<Genre> = blockingClient!!.exchange(request)
        genreIds.add(entityId(response))
        Assertions.assertEquals(HttpStatus.CREATED, response.status)

        request = HttpRequest.POST("/genres", GenreSaveCommand("Microservices")) (4)
        response = blockingClient!!.exchange(request)
        Assertions.assertEquals(HttpStatus.CREATED, response.status)

        val id = entityId(response)
        genreIds.add(id)
        request = HttpRequest.GET<Any>("/genres/$id")
        var genre = blockingClient!!.retrieve(request, Genre::class.java) (5)
        Assertions.assertEquals("Microservices", genre.name)

        request = HttpRequest.PUT("/genres", GenreUpdateCommand(id!!, "Micro-services"))
        response = blockingClient!!.exchange(request) (6)
        Assertions.assertEquals(HttpStatus.NO_CONTENT, response.status)

        request = HttpRequest.GET<Any>("/genres/$id")
        genre = blockingClient!!.retrieve(request, Genre::class.java)
        Assertions.assertEquals("Micro-services", genre.name)

        request = HttpRequest.GET<Any>("/genres/list")
        var genres = blockingClient!!.retrieve(
            request, Argument.listOf(Genre::class.java)
        )
        Assertions.assertEquals(2, genres.size)

        request = HttpRequest.POST("/genres/ex", GenreSaveCommand("Microservices")) (4)
        response = blockingClient!!.exchange(request)
        Assertions.assertEquals(HttpStatus.NO_CONTENT, response.status)

        request = HttpRequest.GET<Any>("/genres/list")
        genres = blockingClient!!.retrieve(
            request, Argument.listOf(Genre::class.java)
        )
        Assertions.assertEquals(2, genres.size)

        request = HttpRequest.GET<Any>("/genres/list?max=1")
        genres = blockingClient!!.retrieve(
            request, Argument.listOf(Genre::class.java)
        )
        Assertions.assertEquals(1, genres.size)
        Assertions.assertEquals("DevOps", genres[0].name)

        request = HttpRequest.GET<Any>("/genres/list?max=1&order=desc&sort=name")
        genres = blockingClient!!.retrieve(
            request, Argument.listOf(Genre::class.java)
        )
        Assertions.assertEquals(1, genres.size)
        Assertions.assertEquals("Micro-services", genres[0].name)

        request = HttpRequest.GET<Any>("/genres/list?max=1&offset=10")
        genres = blockingClient!!.retrieve(
            request, Argument.listOf(Genre::class.java)
        )
        Assertions.assertEquals(0, genres.size)

        // cleanup:
        for (genreId in genreIds) {
            request = HttpRequest.DELETE<Any>("/genres/$genreId")
            response = blockingClient!!.exchange(request)
            Assertions.assertEquals(HttpStatus.NO_CONTENT, response.status)
        }
    }

    private fun entityId(response: HttpResponse<*>): Long? {
        val path = "/genres/"
        val value = response.header(HttpHeaders.LOCATION) ?: return null
        val id = value.substringAfter(path)
        if (id.isBlank()) return null
        return id.toLong()
    }
}
1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. More info.
2 Classes that implement TestPropertyProvider must use this annotation to create a single class instance for all tests (not necessary in Spock tests).
3 Inject the HttpClient bean and point it to the embedded server.
4 Creating HTTP Requests is easy thanks to the Micronaut framework fluid API.
5 If you care just about the object in the response use retrieve.
6 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.

5. Testing the Application

To run the tests:

./gradlew test

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

6. Test Resources

When the application is started locally — either under test or by running the application — resolution of the datasource URL is detected and the Test Resources service will start a local MySQL docker container, and inject the properties required to use this as the datasource.

For more information, see the JDBC section or R2DBC section of the Test Resources documentation.

7. Using MySQL

When you move to production, you will need to configure the properties injected by Test Resources to point at your real production database. This can be done via environment variables like so:

export JPA_DEFAULT_PROPERTIES_HIBERNATE_CONNECTION_URL=jdbc:mysql://localhost:5432/micronaut
export JPA_DEFAULT_PROPERTIES_HIBERNATE_CONNECTION_USERNAME=dbuser
export JPA_DEFAULT_PROPERTIES_HIBERNATE_CONNECTION_PASSWORD=theSecretPassword

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

8. Running the Application

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

..
...
16:31:01.155 [main] INFO  org.hibernate.dialect.Dialect - HHH000400: Using dialect: org.hibernate.dialect.MySQL8Dialect
....

Connect to your MySQL 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" }'

9. Next Steps

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

10. Help with the Micronaut Framework

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

11. License

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