Kotlin / Gradle

Access a database with MyBatis

Learn how to access a database with MyBatis using Micronaut Framework.

Iván López, Sergio del Amo

On this guide

In this section

Getting Started

Learn how to access a database with MyBatis using Micronaut Framework.

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 \
    --features=flyway,jdbc-hikari,mybatis,serialization-jackson,validation,graalvm \
    --build=gradle \
    --lang=kotlin \
    --test=junit

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.

If you use Micronaut Launch, select Micronaut Application as application type and add flyway, jdbc-hikari, mybatis, serialization-jackson, validation, and graalvm features.

Note	If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features, and apply those changes to your application.

Diff

Setup IntelliJ IDEA to develop Micronaut Applications.

Configure Data Source and JPA

Add the following snippet to include the necessary dependencies:

build.gradle

implementation("io.micronaut.sql:micronaut-mybatis") // 
implementation("io.micronaut.sql:micronaut-jdbc-hikari") // 
runtimeOnly("com.h2database:h2") //

1	Add the Micronaut MyBatis dependency.
2	Configure SQL `DataSource` instances using Hikari Connection Pool.
3	Add a dependency to the in-memory H2 database.

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

src/main/resources/application.properties

datasources.default.url=jdbc:h2:mem:default;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
datasources.default.username=sa
datasources.default.password=
datasources.default.driver-class-name=org.h2.Driver

MyBatis Configuration

You can define additional beans which will be used when the MyBatis Configuration is created. Only beans of type MyBatisConfigurationCustomizer with an @Named qualifier matching the datasource name will be applied.

Create a bean to register additional mappers:

kotlin/src/main/kotlin/example/micronaut/CustomConfigurationCustomizer.kt

package example.micronaut

import io.micronaut.configuration.mybatis.MyBatisConfigurationCustomizer
import jakarta.inject.Named
import jakarta.inject.Singleton
import org.apache.ibatis.session.Configuration
import example.micronaut.genre.GenreMapper

@Named("default") // 
@Singleton // 
class CustomConfigurationCustomizer : MyBatisConfigurationCustomizer {
    override fun customize(configuration: Configuration) {
        configuration.addMapper(GenreMapper::class.java) // 
    }
}

1	Declare `@Named` at the class level of a bean to explicitly define the name of the bean.
2	Use `jakarta.inject.Singleton` to designate a class as a singleton.
3	Define additional mappers

Domain

Create the domain entities:

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

package example.micronaut.domain

import com.fasterxml.jackson.annotation.JsonIgnore
import io.micronaut.serde.annotation.Serdeable

@Serdeable
data class Genre(var name: String) {

    var id: Long? = null

    @JsonIgnore
    var books: Set<Book> = mutableSetOf()

    override fun toString() = "Genre{id=$id, name='$name', books=$books}"
}

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

package example.micronaut.domain

import io.micronaut.serde.annotation.Serdeable

@Serdeable
data class Book(
    var isbn: String,
    var name: String,
    var genre: Genre?) {

    var id: Long? = null

    override fun toString() = "Book{id=$id, name='$name', isbn='$isbn', genre=$genre}"
}

Repository Access

Create an interface to define the operations to access the database and use MyBatis annotations to map the methods to SQL queries:

kotlin/src/main/kotlin/example/micronaut/genre/GenreMapper.kt

package example.micronaut.genre

import example.micronaut.domain.Genre
import org.apache.ibatis.annotations.Delete
import org.apache.ibatis.annotations.Insert
import org.apache.ibatis.annotations.Options
import org.apache.ibatis.annotations.Param
import org.apache.ibatis.annotations.Select
import org.apache.ibatis.annotations.Update
import jakarta.validation.constraints.Pattern
import jakarta.validation.constraints.Positive
import jakarta.validation.constraints.PositiveOrZero

interface GenreMapper {

    @Select("select * from genre where id=#{id}")
    fun findById(id: Long): Genre?

    @Insert("insert into genre(name) values(#{name})")
    @Options(useGeneratedKeys = true, keyProperty = "id")
    fun save(genre: Genre)

    @Delete("delete from genre where id=#{id}")
    fun deleteById(id: Long)

    @Update("update genre set name=#{name} where id=#{id}")
    fun update(@Param("id") id: Long, @Param("name") name: String?)

    @Select("select * from genre")
    fun findAll(): List<Genre>

    @Select("select * from genre order by \${sort} \${order}")
    fun findAllBySortAndOrder(@Param("sort") @Pattern(regexp = "id|name") sort: String,
                              @Param("order") @Pattern(regexp = "asc|ASC|desc|DESC") order: String): List<Genre>

    @Select("select * from genre order by \${sort} \${order} limit \${offset}, \${max}")
    fun findAllByOffsetAndMaxAndSortAndOrder(@Param("offset") @PositiveOrZero offset: Int,
                                             @Param("max") @Positive max: Int,
                                             @Param("sort") @Pattern(regexp = "id|name") sort: String,
                                             @Param("order") @Pattern(regexp = "asc|ASC|desc|DESC") order: String): List<Genre>

    @Select("select * from genre limit \${offset}, \${max}")
    fun findAllByOffsetAndMax(@Param("offset") @PositiveOrZero offset: Int,
                              @Param("max") @Positive max: Int): List<Genre>
}

And the implementation:

kotlin/src/main/kotlin/example/micronaut/genre/GenreMapperImpl.kt

package example.micronaut.genre

import example.micronaut.domain.Genre
import jakarta.inject.Singleton
import org.apache.ibatis.session.SqlSession
import org.apache.ibatis.session.SqlSessionFactory
import jakarta.validation.constraints.Pattern
import jakarta.validation.constraints.Positive
import jakarta.validation.constraints.PositiveOrZero

@Singleton // 
open class GenreMapperImpl(private val sqlSessionFactory: SqlSessionFactory) : GenreMapper { // 

    override fun findById(id: Long): Genre? {
        sqlSessionFactory.openSession().use { sqlSession ->  // 
            return getGenreMapper(sqlSession).findById(id) // 
        }
    }

    override fun save(genre: Genre) {
        sqlSessionFactory.openSession().use { sqlSession ->
            getGenreMapper(sqlSession).save(genre)
            sqlSession.commit() // 
        }
    }

    override fun deleteById(id: Long) {
        sqlSessionFactory.openSession().use { sqlSession ->
            getGenreMapper(sqlSession).deleteById(id)
            sqlSession.commit()
        }
    }

    override fun update(id: Long, name: String?) {
        sqlSessionFactory.openSession().use { sqlSession ->
            getGenreMapper(sqlSession).update(id, name)
            sqlSession.commit()
        }
    }

    override fun findAll(): List<Genre> {
        sqlSessionFactory.openSession().use { sqlSession -> return getGenreMapper(sqlSession).findAll() }
    }

    override fun findAllBySortAndOrder(@Pattern(regexp = "id|name") sort: String,
                                       @Pattern(regexp = "asc|ASC|desc|DESC") order: String): List<Genre> {
        sqlSessionFactory.openSession().use { sqlSession ->
            return getGenreMapper(sqlSession).findAllBySortAndOrder(sort, order)
        }
    }

    override fun findAllByOffsetAndMaxAndSortAndOrder(@PositiveOrZero offset: Int,
                                                      @Positive max: Int,
                                                      @Pattern(regexp = "id|name") sort: String,
                                                      @Pattern(regexp = "asc|ASC|desc|DESC") order: String): List<Genre> {
        sqlSessionFactory.openSession().use { sqlSession ->
            return getGenreMapper(sqlSession).findAllByOffsetAndMaxAndSortAndOrder(offset, max, sort, order)
        }
    }

    override fun findAllByOffsetAndMax(@PositiveOrZero offset: Int,
                                       @Positive max: Int): List<Genre> {
        sqlSessionFactory.openSession().use { sqlSession ->
            return getGenreMapper(sqlSession).findAllByOffsetAndMax(offset, max)
        }
    }

    private fun getGenreMapper(sqlSession: SqlSession): GenreMapper {
        return sqlSession.getMapper(GenreMapper::class.java) // 
    }
}

1	Use `jakarta.inject.Singleton` to designate a class as a singleton.
2	Easily inject the `SqlSessionFactory` bean provided by Micronaut MyBatis auto-configuration.
3	Use try-with-resources to automatically close the SQL session.
4	Get MyBatis mapper implementation for the interface.
5	Execute the desired method using the mapper. This will trigger the SQL query.
6	In a database write access, commit the transaction.

Create an interface to define the high-level operations exposed to the application:

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

package example.micronaut.genre

import example.micronaut.ListingArguments
import example.micronaut.domain.Genre
import java.util.Optional
import jakarta.validation.constraints.NotBlank

interface GenreRepository {

    fun findById(id: Long): Optional<Genre>

    fun save(@NotBlank name: String): Genre

    fun deleteById(id: Long)

    fun findAll(args: ListingArguments): List<Genre>

    fun update(id: Long, @NotBlank name: String): Int
}

And the implementation using GenreMapper:

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

package example.micronaut.genre

import example.micronaut.ListingArguments
import example.micronaut.domain.Genre
import io.micronaut.core.annotation.NonNull
import jakarta.inject.Singleton
import java.util.Optional
import jakarta.validation.constraints.NotBlank

@Singleton // 
open class GenreRepositoryImpl(private val genreMapper: GenreMapper) : GenreRepository {

    override fun findById(id: Long): Optional<Genre> =
        Optional.ofNullable(genreMapper.findById(id))

    @NonNull
    override fun save(@NotBlank name: String): Genre {
        val genre = Genre(name)
        genreMapper.save(genre)
        return genre
    }

    override fun deleteById(id: Long) {
        findById(id).ifPresent { genreMapper.deleteById(id) }
    }

    @NonNull
    override fun findAll(args: ListingArguments): List<Genre> {
        if (args.max != null && args.sort != null && args.offset != null && args.order != null) {
            return genreMapper.findAllByOffsetAndMaxAndSortAndOrder(
                args.offset!!,
                args.max!!,
                args.sort!!,
                args.order!!)
        }

        if (args.max != null && args.offset != null) {
            return genreMapper.findAllByOffsetAndMax(args.offset!!, args.max!!)
        }

        if (args.sort != null && args.order != null) {
            return genreMapper.findAllBySortAndOrder(args.sort!!, args.order!!)
        }

        return genreMapper.findAll()
    }

    override fun update(id: Long, @NotBlank name: String): Int {
        genreMapper.update(id, name)
        return -1
    }
}

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:

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

package example.micronaut.genre

import io.micronaut.serde.annotation.Serdeable
import jakarta.validation.constraints.NotBlank

@Serdeable
data class GenreSaveCommand(@NotBlank var name: String)

kotlin/src/main/kotlin/example/micronaut/genre/GenreUpdateCommand.kt

package example.micronaut.genre

import io.micronaut.serde.annotation.Serdeable
import jakarta.validation.constraints.NotBlank

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

Create a POJO to encapsulate sorting and pagination:

kotlin/src/main/kotlin/example/micronaut/ListingArguments.kt

package example.micronaut

import io.micronaut.serde.annotation.Serdeable
import io.micronaut.http.uri.UriBuilder
import java.net.URI
import jakarta.validation.constraints.Pattern
import jakarta.validation.constraints.Positive
import jakarta.validation.constraints.PositiveOrZero

@Serdeable
class ListingArguments(
    @field:PositiveOrZero var offset: Int? = 0,
    @field:Positive var max: Int? = null,
    @field:Pattern(regexp = "id|name") var sort: String? = null,
    @field:Pattern(regexp = "asc|ASC|desc|DESC") var order: String? = null
) {
    fun of(uriBuilder: UriBuilder): URI {
        max?.let { uriBuilder.queryParam("max", it) }
        order?.let { uriBuilder.queryParam("order", it) }
        offset?.let { uriBuilder.queryParam("offset", it) }
        sort?.let { uriBuilder.queryParam("sort", it) }
        return uriBuilder.build()
    }

    class Builder {
        private val args = ListingArguments()

        fun max(max: Int): Builder = apply { args.max = max }
        fun sort(sort: String?): Builder = apply { args.sort = sort }
        fun order(order: String?): Builder = apply { args.order = order }
        fun offset(offset: Int): Builder = apply { args.offset = offset }
        fun build(): ListingArguments = args
    }

    companion object {
        fun builder(): Builder = Builder()
    }
}

Create a ConfigurationProperties class to encapsulate the configuration of the default max value.

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

package example.micronaut

interface ApplicationConfiguration {
    val max: Int
}

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

package example.micronaut

import io.micronaut.context.annotation.ConfigurationProperties

@ConfigurationProperties("application") // 
class ApplicationConfigurationProperties : ApplicationConfiguration {

    private val DEFAULT_MAX = 10

    override var max = DEFAULT_MAX
}

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

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

package example.micronaut

import example.micronaut.domain.Genre
import example.micronaut.genre.GenreRepository
import example.micronaut.genre.GenreSaveCommand
import example.micronaut.genre.GenreUpdateCommand
import io.micronaut.http.HttpHeaders.LOCATION
import io.micronaut.http.HttpResponse
import io.micronaut.http.MutableHttpHeaders
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 java.net.URI
import jakarta.validation.Valid

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

    @Get("/{id}") // 
    fun show(id: Long): Genre? = genreRepository.findById(id).orElse(null) // 

    @Put // 
    open fun update(@Body @Valid command: GenreUpdateCommand): HttpResponse<*> { // 
        genreRepository.update(command.id, command.name)
        return HttpResponse
                .noContent<Any>()
                .header(LOCATION, location(command.id).path) // 
    }

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

    @Post // 
    open fun save(@Body @Valid cmd: GenreSaveCommand): HttpResponse<Genre> {
        val genre = genreRepository.save(cmd.name)
        return HttpResponse
                .created(genre)
                .headers { headers: MutableHttpHeaders -> headers.location(location(genre.id)) }
    }

    @Delete("/{id}") // 
    fun delete(id: Long): HttpResponse<*> {
        genreRepository.deleteById(id)
        return HttpResponse.noContent<Any>()
    }

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

1	The class is defined as a controller with the @Controller annotation mapped to the path `/genres`.
2	Constructor injection.
3	Maps a `GET` request to `/genres/{id}`, which attempts to show a genre. This illustrates the use of a URL path variable.
4	Returning `null` when the genre doesn’t exist makes 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 that requires validation. Use a POJO supplied as a JSON payload in the request to populate the command.
7	It is easy to add custom headers to the response.
8	Maps a `GET` request to `/genres`, which returns a list of genres. This mapping illustrates optional URL parameters.
9	Maps a `POST` request to `/genres`, which attempts to save a genre.
10	Maps a `DELETE` request to `/genres/{id}`, which attempts to remove a genre. This illustrates the use of a URL path variable.

Database Migration with Flyway

We need a way to create the database schema. For that, we use Micronaut integration with Flyway.

Flyway automates schema changes, significantly simplifying schema management tasks, such as migrating, rolling back, and reproducing in multiple environments.

Add the following snippet to include the necessary dependencies:

build.gradle

implementation("io.micronaut.flyway:micronaut-flyway")

We will enable Flyway in the Micronaut configuration file and configure it to perform migrations on one of the defined data sources.

src/main/resources/application.properties

flyway.datasources.default.enabled=true

1	Enable Flyway for the `default` datasource.

Note	Configuring multiple data sources is as simple as enabling Flyway for each one. You can also specify directories that will be used for migrating each data source. Review the Micronaut Flyway documentation for additional details.

Flyway migration will be automatically triggered before your Micronaut application starts. Flyway will read migration commands in the resources/db/migration/ directory, execute them if necessary, and verify that the configured data source is consistent with them.

Create the following migration files with the database schema creation:

src/main/resources/db/migration/V1__schema.sql

DROP TABLE IF EXISTS GENRE;
DROP TABLE IF EXISTS BOOK;

CREATE TABLE GENRE (
  id    BIGINT AUTO_INCREMENT PRIMARY KEY NOT NULL,
  name VARCHAR(255)              NOT NULL UNIQUE
);

CREATE TABLE BOOK (
  id    BIGINT AUTO_INCREMENT PRIMARY KEY NOT NULL,
  name VARCHAR(255)              NOT NULL,
  isbn VARCHAR(255)              NOT NULL,
  genre_id BIGINT,
    constraint FKM1T3YVW5I7OLWDF32CWUUL7TA
    foreign key (GENRE_ID) references GENRE
);

During application startup, Flyway will execute the SQL file and create the schema needed for the application.

Tests

Create a JUnit test to verify the CRUD operations:

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

package example.micronaut

import example.micronaut.domain.Genre
import example.micronaut.genre.GenreSaveCommand
import example.micronaut.genre.GenreUpdateCommand
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.CREATED
import io.micronaut.http.HttpStatus.NO_CONTENT
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.http.uri.UriBuilder
import io.micronaut.http.uri.UriTemplate
import io.micronaut.test.extensions.junit5.annotation.MicronautTest
import jakarta.inject.Inject
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertThrows
import org.junit.jupiter.api.Test
import java.util.Collections

@MicronautTest // 
class GenreControllerTest(@Client("/") val httpClient: HttpClient) { // 

    @Test
    fun supplyAnInvalidOrderTriggersValidationFailure() {
        assertThrows(HttpClientResponseException::class.java) {
            client.retrieve(
                    HttpRequest.GET<Any>("/genres/list?order=foo"),
                    Argument.of(List::class.java, Genre::class.java))
        }
    }

    @Test
    fun testFindNonExistingGenreReturns404() {
        assertThrows(HttpClientResponseException::class.java) {
            client.retrieve(HttpRequest.GET<Any>("/genres/99"), Argument.of(Genre::class.java))
        }
    }

    @Test
    fun testGenreCrudOperations() {
        val genreIds = mutableListOf<Long>()

        var response = saveGenre("DevOps")
        genreIds.add(entityId(response)!!)
        assertEquals(CREATED, response.status)

        response = saveGenre("Microservices") // 
        assertEquals(CREATED, response.status)

        val id = entityId(response)
        genreIds.add(id!!)
        var genre = show(id)
        assertEquals("Microservices", genre.name)

        response = update(id, "Micro-services")
        assertEquals(NO_CONTENT, response.status)

        genre = show(id)
        assertEquals("Micro-services", genre.name)

        var genres = listGenres(ListingArguments.builder().build())
        assertEquals(2, genres.size)

        genres = listGenres(ListingArguments.builder().max(1).build())
        assertEquals(1, genres.size)
        assertEquals("DevOps", genres[0].name)

        genres = listGenres(ListingArguments.builder().max(1).order("desc").sort("name").build())
        assertEquals(1, genres.size)
        assertEquals("Micro-services", genres[0].name)

        genres = listGenres(ListingArguments.builder().max(1).offset(10).build())
        assertEquals(0, genres.size)

        // cleanup:
        for (genreId in genreIds) {
            response = delete(genreId)
            assertEquals(NO_CONTENT, response.status)
        }
    }

    private fun listGenres(args: ListingArguments): List<Genre> {
        val uri = args.of(UriBuilder.of("/genres/list"))
        val request: HttpRequest<*> = HttpRequest.GET<Any>(uri)
        return client.retrieve(request, Argument.of(List::class.java, Genre::class.java)) as List<Genre> // 
    }

    private fun show(id: Long?): Genre {
        val uri = UriTemplate.of("/genres/{id}").expand(Collections.singletonMap<String, Any?>("id", id))
        val request: HttpRequest<*> = HttpRequest.GET<Any>(uri)
        return client.retrieve(request, Genre::class.java)
    }

    private fun update(id: Long?, name: String): HttpResponse<Any> {
        val request: HttpRequest<*> = HttpRequest.PUT("/genres", GenreUpdateCommand(id!!, name))
        return client.exchange(request) // 
    }

    private fun delete(id: Long): HttpResponse<Any> {
        val request: HttpRequest<*> = HttpRequest.DELETE<Any>("/genres/$id")
        return client.exchange(request)
    }

    private fun entityId(response: HttpResponse<Any>): Long? {
        val value = response.header(HttpHeaders.LOCATION) ?: return null
        val path = "/genres/"
        val index = value.indexOf(path)
        return if (index != -1) {
            java.lang.Long.valueOf(value.substring(index + path.length))
        } else null
    }

    private val client: BlockingHttpClient
        get() = httpClient.toBlocking()

    private fun saveGenre(genre: String): HttpResponse<Any> {
        val request: HttpRequest<*> = HttpRequest.POST("/genres", GenreSaveCommand(genre)) // 
        return client.exchange(request)
    }
}

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 only 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`, use the `exchange` method.

Run the tests:

./gradlew test

Running the App

Running the Application

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

We can use curl to check that everything works as expected:

curl http://localhost:8080/genres/list

[]

curl -X POST -d '{"name":"Sci-fi"}' -H "Content-Type: application/json" http://localhost:8080/genres

{"id":1,"name":"Sci-fi"}

curl -X POST -d '{"name":"Science"}' -H "Content-Type: application/json" http://localhost:8080/genres

{"id":2,"name":"Science"}

curl http://localhost:8080/genres/list

[{"id":1,"name":"Sci-fi"},{"id":2,"name":"Science"}]

curl -X DELETE http://localhost:8080/genres/1

curl http://localhost:8080/genres/list

[{"id":2,"name":"Science"}]

Generate a Micronaut Application Native Executable with GraalVM

We will use GraalVM, an advanced JDK with ahead-of-time Native Image compilation, to generate a native executable of this Micronaut application.

Compiling Micronaut applications ahead of time with GraalVM significantly improves startup time and reduces the memory footprint of JVM-based applications.

Note	Only Java and Kotlin projects support using GraalVM’s `native-image` tool. Groovy relies heavily on reflection, which is only partially supported by GraalVM.

GraalVM Installation

The easiest way to install GraalVM on Linux or Mac is to use SDKMan.io.

Java 25

sdk install java 25.0.2-graal

For installation on Windows, or for a manual installation on Linux or Mac, see the GraalVM Getting Started documentation.

The previous command installs Oracle GraalVM, which is free to use in production and free to redistribute, at no cost, under the GraalVM Free Terms and Conditions.

Alternatively, you can use the GraalVM Community Edition:

Java 25

sdk install java 25.0.2-graalce

Native Executable Generation

To generate a native executable using Gradle, run:

./gradlew nativeCompile

The native executable is created in build/native/nativeCompile directory and can be run with build/native/nativeCompile/micronautguide.

It is possible to customize the name of the native executable or pass additional parameters to GraalVM:

build.gradle

graalvmNative {
    binaries {
        main {
            imageName.set('mn-graalvm-application') // 
            buildArgs.add('-Ob') // 
        }
    }
}

1	The native executable name will now be `mn-graalvm-application`
2	It is possible to pass extra build arguments to `native-image`. For example, `-Ob` enables the quick build mode.

You can execute the same curl request as before to check that the native executable works.

Next Steps

Read more about the Configurations for Data Access section and Flyway support in the Micronaut Framework 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).