These tutorials target Micronaut Framework 3. Read, Guides for Micronaut Framework 4.

Table of Contents

Access a MongoDB database asynchronously with Micronaut Data MongoDB and Reactive Streams

Learn how to access a MongoDB database asynchronously with Micronaut Data.

Authors: Tim Yates

Micronaut Version: 3.9.2

1. Getting Started

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

You will use MongoDB for persistence.

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 \
    --features=data-mongodb-reactive,reactor,testcontainers \
    --build=gradle
    --lang=groovy
If you don’t specify the --build argument, Gradle is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.

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 data-mongodb-reactive, reactor, and testcontainers features.

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.

Setup IntelliJ IDEA to develop Micronaut Applications.

4.1. Dependencies

In this guide, we use the MongoDB Reactive driver.

The data-mongodb-reactive features adds the following dependencies:

build.gradle
compileOnly("io.micronaut.data:micronaut-data-document-processor")
implementation("io.micronaut.data:micronaut-data-mongodb")
implementation("org.mongodb:mongodb-driver-reactivestreams")

4.2. POGO

Create a Fruit POGO:

src/main/groovy/example/micronaut/Fruit.groovy
package example.micronaut

import io.micronaut.core.annotation.NonNull
import io.micronaut.core.annotation.Nullable
import io.micronaut.data.annotation.GeneratedValue
import io.micronaut.data.annotation.Id
import io.micronaut.data.annotation.MappedEntity

import javax.validation.constraints.NotBlank

@MappedEntity (1)
class Fruit {

    @Id (2)
    @GeneratedValue
    String id

    @NonNull
    @NotBlank (3)
    final String name

    @Nullable
    String description

    Fruit(@NonNull String name, @Nullable String description) {
        this.name = name
        this.description = description
    }
}
1 Annotate the class with @MappedEntity to map the class to the table defined in the schema.
2 Specifies the ID of an entity
3 Use javax.validation.constraints Constraints to ensure the data matches your expectations.

4.3. Repository

Create a repository interface to encapsulate the CRUD actions for Fruit.

src/main/groovy/example/micronaut/FruitRepository.groovy
package example.micronaut

import io.micronaut.core.annotation.NonNull
import io.micronaut.data.mongodb.annotation.MongoRepository
import io.micronaut.data.repository.reactive.ReactiveStreamsCrudRepository
import org.reactivestreams.Publisher

@MongoRepository (1)
interface FruitRepository extends ReactiveStreamsCrudRepository<Fruit, String> { (2)

    @NonNull
    Publisher<Fruit> findByNameInList(@NonNull List<String> names) (3)
}
1 Annotate with @MongoRepository.
2 Extend ReactiveStreamsCrudRepository for asynchronous database access.
3 Add a finder for finding fruit by a list of names.

4.4. Service

Create a service FruitService as an API to interact with the Fruit repository. This will allow you to keep business logic out of the controller, and to test the controller later without interacting with a real database.

src/main/groovy/example/micronaut/FruitService.groovy
package example.micronaut

import io.micronaut.core.annotation.NonNull
import org.reactivestreams.Publisher

interface FruitService {

    Publisher<Fruit> list()

    Publisher<Fruit> save(Fruit fruit)

    Publisher<Fruit> find(@NonNull String id)

    Publisher<Fruit> findByNameInList(List<String> name)
}

And then create a default implementation of this service.

src/main/groovy/example/micronaut/DefaultFruitService.groovy
package example.micronaut

import io.micronaut.core.annotation.NonNull
import jakarta.inject.Singleton
import org.reactivestreams.Publisher

@Singleton (1)
class DefaultFruitService implements FruitService {

    private final FruitRepository fruitRepository

    DefaultFruitService(FruitRepository fruitRepository) {
        this.fruitRepository = fruitRepository
    }

    Publisher<Fruit> list() {
        fruitRepository.findAll()
    }

    Publisher<Fruit> save(Fruit fruit) {
        if (fruit.getId() == null) {
            fruitRepository.save(fruit)
        } else {
            fruitRepository.update(fruit)
        }
    }

    Publisher<Fruit> find(@NonNull String id) {
        fruitRepository.findById(id)
    }

    Publisher<Fruit> findByNameInList(List<String> name) {
        fruitRepository.findByNameInList(name)
    }
}
1 Use jakarta.inject.Singleton to designate a class as a singleton.

4.5. Controller

Create FruitController:

src/main/groovy/example/micronaut/FruitController.groovy
package example.micronaut

import io.micronaut.core.annotation.NonNull
import io.micronaut.http.HttpStatus
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.PathVariable
import io.micronaut.http.annotation.Post
import io.micronaut.http.annotation.Put
import io.micronaut.http.annotation.QueryValue
import io.micronaut.http.annotation.Status
import org.reactivestreams.Publisher

import javax.validation.Valid
import javax.validation.constraints.NotNull

@Controller("/fruits") (1)
class FruitController {

    private final FruitService fruitService

    FruitController(FruitService fruitService) {  (2)
        this.fruitService = fruitService
    }

    @Get  (3)
    Publisher<Fruit> list() {
        fruitService.list()
    }

    @Post (4)
    @Status(HttpStatus.CREATED) (5)
    Publisher<Fruit> save(@NonNull @NotNull @Valid Fruit fruit) { (6)
        fruitService.save(fruit)
    }

    @Put
    Publisher<Fruit> update(@NonNull @NotNull @Valid Fruit fruit) {
        fruitService.save(fruit)
    }

    @Get("/{id}") (7)
    Publisher<Fruit> find(@PathVariable String id) {
        fruitService.find(id)
    }

    @Get("/q") (8)
    Publisher<Fruit> query(@QueryValue @NotNull List<String> names) { (9)
        fruitService.findByNameInList(names)
    }
}
1 The class is defined as a controller with the @Controller annotation mapped to the path /fruits.
2 Use constructor injection to inject a bean of type FruitService.
3 The @Get annotation maps the list method to an HTTP GET request on /fruits.
4 The @Post annotation maps the save method to an HTTP POST request on /fruits.
5 You can specify the HTTP status code via the @Status annotation.
6 Add @Valid to any method parameter which requires validation.
7 The @Get annotation maps the find method to an HTTP GET request on /fruits/{id}.
8 The @Get annotation maps the findByNameInList method to an HTTP GET request on /fruits/q.
9 Bind a list of Strings to the query parameter names

4.6. Test Client

Add a Micronaut declarative HTTP Client to src/test to ease the testing of the application’s API.

src/test/groovy/example/micronaut/FruitClient.groovy
package example.micronaut

import io.micronaut.http.HttpResponse
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.PathVariable
import io.micronaut.http.annotation.Post
import io.micronaut.http.annotation.Put
import io.micronaut.http.annotation.QueryValue
import io.micronaut.http.client.annotation.Client

import javax.validation.constraints.NotNull

@Client("/fruits")
interface FruitClient {

    @Get
    Iterable<Fruit> list()

    @Get("/{id}")
    Optional<Fruit> find(@PathVariable String id)

    @Get("/q")
    Iterable<Fruit> query(@QueryValue @NotNull List<String> names)

    @Post
    HttpResponse<Fruit> save(Fruit fruit)

    @Put
    Fruit update(Fruit fruit)
}

Then create a test that verifies the validation of the Fruit POJO when we create a new entity via POST:

src/test/groovy/example/micronaut/FruitValidationControllerSpec.groovy
package example.micronaut

import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpStatus
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

@MicronautTest(transactional = false) (1)
class FruitValidationControllerSpec extends Specification {

    @Inject
    @Client("/")
    HttpClient httpClient

    void "fruit is validated"() {
        when:
        httpClient.toBlocking().exchange(HttpRequest.POST('/fruits', new Fruit('', 'Hola')))

        then:
        HttpClientResponseException e = thrown()
        e.status == HttpStatus.BAD_REQUEST
    }
}
1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. By default, each @Test method will be wrapped in a transaction that will be rolled back when the test finishes. This behaviour is is changed by setting transaction to false.
Transaction mode is not supported when the synchronous transaction manager is created using Reactive transaction manager!

Create a test that checks our controller works against a real MongoDB database:

src/test/groovy/example/micronaut/FruitControllerSpec.groovy
package example.micronaut

import io.micronaut.http.HttpResponse
import io.micronaut.http.HttpStatus
import io.micronaut.test.extensions.spock.annotation.MicronautTest
import jakarta.inject.Inject
import spock.lang.Specification

@MicronautTest(transactional = false) (1)
class FruitControllerSpec extends Specification {

    @Inject
    FruitClient fruitClient

    void "empty database contains no fruit"() {
        expect:
        fruitClient.list().empty
    }

    void "fruits endpoint interacts with mongodb"() {
        when:
        HttpResponse<Fruit> response = fruitClient.save(new Fruit('banana', null))

        then:
        response.status == HttpStatus.CREATED
        def banana = response.body.get()

        when:
        Iterable<Fruit> fruits = fruitClient.list()

        then:
        fruits*.name == ['banana']
        fruits*.description == [null]

        when:
        response = fruitClient.save(new Fruit('Apple', 'Keeps the doctor away'))

        then:
        response.status == HttpStatus.CREATED

        when:
        fruits = fruitClient.list()

        then:
        fruits.find { it.description == 'Keeps the doctor away' }

        when: 'we update the description'
        banana.description = 'Yellow and curved'
        fruitClient.update(banana)

        and: 'we get a list of known fruits'
        fruits = fruitClient.list()

        then: 'descriptions are updated'
        fruits*.description.toSet() == ['Keeps the doctor away', 'Yellow and curved'] as Set<String>
    }

    void "search works as expected"() {
        given:
        fruitClient.save(new Fruit('apple', 'Keeps the doctor away'))
        fruitClient.save(new Fruit('pineapple', 'Delicious'))
        fruitClient.save(new Fruit('lemon', 'Lemonentary my dear Dr Watson'))

        when:
        Iterable<Fruit> fruit = fruitClient.query(["apple", "pineapple"])

        then:
        fruit*.name.toSet() == ['apple', 'pineapple'] as Set<String>
    }

}
1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. By default, each @Test method will be wrapped in a transaction that will be rolled back when the test finishes. This behaviour is is changed by setting transaction to false.

And finally, create a test which uses a replacement FruitService to test the controller without touching the database:

src/test/groovy/example/micronaut/ControllerIsolationSpec.groovy
package example.micronaut

import io.micronaut.context.annotation.Property
import io.micronaut.context.annotation.Replaces
import io.micronaut.context.annotation.Requires
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.MediaType
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.test.extensions.spock.annotation.MicronautTest
import jakarta.inject.Inject
import jakarta.inject.Singleton
import org.jetbrains.annotations.NotNull
import org.reactivestreams.Publisher
import reactor.core.publisher.Flux
import reactor.core.publisher.Mono
import spock.lang.Specification

@MicronautTest(transactional = false) (1)
@Property(name = "spec.name", value = "controller-isolation")
class ControllerIsolationSpec extends Specification {

    @Inject
    @Client("/")
    HttpClient httpClient

    void checkSerialization() {
        when:
        def get = HttpRequest.GET('/fruits')
        HttpResponse<List<Fruit>> response = httpClient.toBlocking().exchange(get, Argument.listOf(Fruit.class))

        then:
        response.status == HttpStatus.OK
        response.headers.get(HttpHeaders.CONTENT_TYPE) == MediaType.APPLICATION_JSON
        response.getBody().present

        response.body().collect { [it.name, it.description]} == [ ["apple", "red"], ["banana", "yellow"] ]
    }

    @Singleton
    @Replaces(DefaultFruitService.class)
    @Requires(property = "spec.name", value = "controller-isolation")
    static class MockService implements FruitService {

        @Override
        Publisher<Fruit> list() {
            Flux.just(new Fruit("apple", "red"), new Fruit("banana", "yellow"))
        }

        @Override
        Publisher<Fruit> save(Fruit fruit) {
            Mono.just(fruit)
        }

        @Override
        Publisher<Fruit> find(@NotNull String id) {
            Mono.empty()
        }

        @Override
        Publisher<Fruit> findByNameInList(List<String> name) {
            Flux.empty()
        }
    }
}
1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. By default, each @Test method will be wrapped in a transaction that will be rolled back when the test finishes. This behaviour is is changed by setting transaction to false.

5. Test Resources

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

When running under production, you should replace this property with the location of your production MongoDB instance via an environment variable.

MONGODB_URI=mongodb://username:password@production-server:27017/databaseName

For more information, see the MongoDB section of the Test Resources documentation.

6. Testing the Application

To run the tests:

./gradlew test

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

7. Running the Application

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

curl -d '{"name":"Pear"}' \
     -H "Content-Type: application/json" \
     -X POST http://localhost:8080/fruits
curl -i localhost:8080/fruits
HTTP/1.1 200 OK
date: Wed, 15 Sep 2021 12:40:15 GMT
Content-Type: application/json
content-length: 110
connection: keep-alive

[{"name":"Pear"}]

8. Next steps

Explore more features with Micronaut Guides.

Read more about the integration between the Micronaut Data and MongoDB.

9. Help with the Micronaut Framework

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