On this page

MongoDB

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:

Learn how to access a MongoDB database with Micronaut Data and the MongoDB Sync driver.
Learn how to access a MongoDB database asynchronously with Micronaut Data.

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.

GORM is not supported in Micronaut Framework 4.x. The setup instructions for using it are no longer relevant and have been removed.

4 Setting up the Mongo Driver

Tip	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

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

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