Micronaut MongoDB

Integration between Micronaut and MongoDB

Version: 1.1.0

1 Introduction

This project includes integration between Micronaut and MongoDB.

Release History

1.1.0

  • Upgrade to mongo-java-driver3.10.0

  • Upgrade to mongodb-driver-reactivestreams1.10.0

2 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:

compile 'io.micronaut.configuration:micronaut-mongo-reactive'
<dependency>
    <groupId>io.micronaut.configuration</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 mongo-java-driver.

compile "org.mongodb:mongo-java-driver"

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.

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

4 MongoDB and Testing

For testing you can add a dependency on Embedded MongoDB and if the MongoDB server is not available on the configured port for the test environment an embedded MongoDB will be bootstrapped and made available for testing:

testCompile 'de.flapdoodle.embed:de.flapdoodle.embed.mongo:2.0.1'
<dependency>
    <groupId>de.flapdoodle.embed</groupId>
    <artifactId>de.flapdoodle.embed.mongo</artifactId>
    <version>2.0.1</version>
    <scope>test</scope>
</dependency>