[ + ]

Table of Contents

Micronaut MongoDB

Integration between Micronaut and MongoDB

Version:

1 Introduction

This project includes integration between Micronaut and MongoDB.

Note that this project provides only low-level access to the MongoDB client drivers (both synchronous and reactive). If you are looking for a more complete experience including support for data access repositories see the documentation for Micronaut Data MongoDB as well as these useful guides:

2 Release History

For this project, you can find a list of releases (with release notes) here:

https://github.com/micronaut-projects/micronaut-mongodb/releases

3 Breaking Changes

Version 5.0.0

Support for testing with flapdoodle has been removed. Please use test-containers instead as described under MongoDB and Testing.

4 Setting up the Mongo Driver

Using the CLI

If you are creating your project using the Micronaut CLI, supply the mongo-reactive feature to configure the native MongoDB driver in your project:

$ mn create-app my-app --features mongo-reactive

Micronaut includes a configuration to automatically configure the native MongoDB Java driver. To use this configuration, add the following dependency to your application:

implementation("io.micronaut.mongodb:micronaut-mongo-reactive")
<dependency>
    <groupId>io.micronaut.mongodb</groupId>
    <artifactId>micronaut-mongo-reactive</artifactId>
</dependency>

Then configure the URI of the MongoDB server in application.yml:

Configuring a MongoDB server
mongodb:
    uri: mongodb://username:password@localhost:27017/databaseName
The mongodb.uri follows the MongoDB Connection String format.

A non-blocking Reactive Streams MongoClient is then available for dependency injection.

To use the blocking driver, add a dependency to your application to the micronaut-mongo-sync module.

implementation("io.micronaut.mongodb:micronaut-mongo-sync")
<dependency>
    <groupId>io.micronaut.mongodb</groupId>
    <artifactId>micronaut-mongo-sync</artifactId>
</dependency>

Then the blocking MongoClient will be available for injection.

Using GORM for MongoDB

Using the CLI

If you are creating your project using the Micronaut CLI, supply the mongo-gorm feature to configure GORM for MongoDB in your project:

$ mn create-app my-app --features mongo-gorm

For Groovy users and users familiar with Grails, special support has been added to Micronaut for using GORM for MongoDB.

To add support for GORM for MongoDB, first configure the MongoDB connection as per instructions earlier in the guide, then add the following dependency to your application:

build.gradle
compile "io.micronaut.configuration:micronaut-mongo-gorm"
For GORM for MongoDB you will need to configure the database name separately as the grails.mongodb.databaseName property in application.yml.

The following should be noted regarding using GORM for MongoDB in Micronaut:

  • Each class you wish to be a GORM entity should be annotated with the grails.gorm.annotation.Entity annotation.

  • Each method that interacts with GORM should be annotated with GORM’s grails.gorm.transactions.Transactional to ensure a session is present. You can also add the @Transactional annotation to the class.

  • By default Micronaut will scan for entities relative to your Application class. If you wish to customize this specify additional packages via the ApplicationContextBuilder when starting your application.

5 Configuring the Mongo Driver

The configuration options for the blocking client and the non-blocking client differ at the driver level.

To configure the blocking client options you can use the mongodb.options setting which allows you to configure any property of the MongoClientOptions.Builder class. For example in application.yml:

Configuring Blocking Driver Options
mongodb:
    ...
    options:
        maxConnectionIdleTime: 10000
        readConcern: majority

See the API for DefaultMongoConfiguration for more information on the available configuration options.

For the Reactive driver, the DefaultReactiveMongoConfiguration exposes options to configure the Reactive Streams driver. For example:

Configuring the Reactive Streams Driver
mongodb:
    ...
    cluster:
        maxWaitQueueSize: 5
    connectionPool:
        maxSize: 20

Multiple MongoDB Drivers

You can create multiple MongoDB connections using the mongodb.servers setting. For example in application.yml:

Configuring Multiple MongoDB Drivers
mongodb:
    servers:
        another:
            uri: mongodb://localhost:27018

With the above configuration in place you can inject a MongoClient using the name another:

import com.mongodb.reactivestreams.client.*;
import jakarta.inject.*;
...
@Inject @Named("another") MongoClient mongoClient;

MongoDB Health Checks

When the mongo-reactive module is activated a MongoHealthIndicator is activated resulting in the /health endpoint and CurrentHealthStatus interface resolving the health of the MongoDB connection.

See the section on the Health Endpoint for more information.

6 MongoDB and Testing

The MongoDb support in Micronaut Test Resources – which uses the Testcontainers library for Java – is the recommended way to test Mongo interaction.

Alternatively, Testcontainers for Java can be used directly to test Mongo interaction. For Spock tests this is a simple matter of:

@Shared @AutoCleanup GenericContainer mongo =
        new GenericContainer("mongo:4.0")
                .withExposedPorts(27017)

def setupSpec() {
    mongo.start()
}

7 Repository

You can find the source code of this project in this repository:

https://github.com/micronaut-projects/micronaut-mongodb