Back to Guides
Edit this Page

Using the MongoDB Client

MongoDB is a well known NoSQL Database that is widely used.

In this guide, we see how you can get your REST services to use the MongoDB database.

Prerequisites

To complete this guide, you need:

  • Roughly 15 minutes

  • An IDE

  • JDK 17+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.9.9

  • Optionally the Quarkus CLI if you want to use it

  • Optionally Mandrel or GraalVM installed and configured appropriately if you want to build a native executable (or Docker if you use a native container build)

  • MongoDB installed or Docker installed

Architecture

The application built in this guide is quite simple: the user can add elements in a list using a form and the list is updated.

All the information between the browser and the server is formatted as JSON.

The elements are stored in MongoDB.

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.

Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.

The solution is located in the mongodb-quickstart directory.

Creating the Maven project

First, we need a new project. Create a new project with the following command:

CLI
quarkus create app org.acme:mongodb-quickstart \
    --extension='rest-jackson,mongodb-client' \
    --no-code
cd mongodb-quickstart

To create a Gradle project, add the --gradle or --gradle-kotlin-dsl option.

For more information about how to install and use the Quarkus CLI, see the Quarkus CLI guide.

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.17.5:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=mongodb-quickstart \
    -Dextensions='rest-jackson,mongodb-client' \
    -DnoCode
cd mongodb-quickstart

To create a Gradle project, add the -DbuildTool=gradle or -DbuildTool=gradle-kotlin-dsl option.

For Windows users:

  • If using cmd, (don’t use backward slash \ and put everything on the same line)

  • If using Powershell, wrap -D parameters in double quotes e.g. "-DprojectArtifactId=mongodb-quickstart"

This command generates a Maven structure importing the Quarkus REST (formerly RESTEasy Reactive) Jackson and MongoDB Client extensions. After this, the quarkus-mongodb-client extension has been added to your build file.

If you already have your Quarkus project configured, you can add the mongodb-client extension to your project by running the following command in your project base directory:

CLI
quarkus extension add mongodb-client
Maven
./mvnw quarkus:add-extension -Dextensions='mongodb-client'
Gradle
./gradlew addExtension --extensions='mongodb-client'

This will add the following to your pom.xml:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-mongodb-client</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-mongodb-client")

Creating your first JSON REST service

In this example, we will create an application to manage a list of fruits.

First, let’s create the Fruit bean as follows:

package org.acme.mongodb;

import java.util.Objects;

public class Fruit {

    private String name;
    private String description;
    private String id;

    public Fruit() {
    }

    public Fruit(String name, String description) {
        this.name = name;
        this.description = description;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    @Override
    public boolean equals(Object obj) {
        if (!(obj instanceof Fruit)) {
            return false;
        }

        Fruit other = (Fruit) obj;

        return Objects.equals(other.name, this.name);
    }

    @Override
    public int hashCode() {
        return Objects.hash(this.name);
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getId() {
        return id;
    }
}

Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer.

Now create a org.acme.mongodb.FruitService that will be the business layer of our application and store/load the fruits from the mongoDB database.

package org.acme.mongodb;

import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoCursor;
import org.bson.Document;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import java.util.ArrayList;
import java.util.List;

@ApplicationScoped
public class FruitService {

    @Inject MongoClient mongoClient;

    public List<Fruit> list(){
        List<Fruit> list = new ArrayList<>();
        MongoCursor<Document> cursor = getCollection().find().iterator();

        try {
            while (cursor.hasNext()) {
                Document document = cursor.next();
                Fruit fruit = new Fruit();
                fruit.setName(document.getString("name"));
                fruit.setDescription(document.getString("description"));
                list.add(fruit);
            }
        } finally {
            cursor.close();
        }
        return list;
    }

    public void add(Fruit fruit){
        Document document = new Document()
                .append("name", fruit.getName())
                .append("description", fruit.getDescription());
        getCollection().insertOne(document);
    }

    private MongoCollection getCollection(){
        return mongoClient.getDatabase("fruit").getCollection("fruit");
    }
}

Now, create the org.acme.mongodb.FruitResource class as follows:

@Path("/fruits")
public class FruitResource {

    @Inject FruitService fruitService;

    @GET
    public List<Fruit> list() {
        return fruitService.list();
    }

    @POST
    public List<Fruit> add(Fruit fruit) {
        fruitService.add(fruit);
        return list();
    }
}

The implementation is pretty straightforward, and you just need to define your endpoints using the Jakarta REST annotations and use the FruitService to list/add new fruits.

Configuring the MongoDB database

The main property to configure is the URL to access to MongoDB. Almost all configuration can be included in the connection URI, so we advise you to do so. You can find more information in the MongoDB documentation: https://docs.mongodb.com/manual/reference/connection-string/

A sample configuration should look like this:

# configure the mongoDB client for a replica set of two nodes
quarkus.mongodb.connection-string = mongodb://mongo1:27017,mongo2:27017

In this example, we are using a single instance running on localhost:

# configure the mongoDB client for a single instance on localhost
quarkus.mongodb.connection-string = mongodb://localhost:27017

If you need more configuration properties, there is a full list at the end of this guide.

By default, Quarkus will restrict the use of JNDI within an application, as a precaution to try and mitigate any future vulnerabilities similar to Log4Shell. Because the mongo+srv protocol often used to connect to MongoDB requires JNDI, this protection is automatically disabled when using the MongoDB client extension.

Use the MongoDB Dev Services

See MongoDB Dev Services.

Multiple MongoDB Clients

MongoDB allows you to configure multiple clients. Using several clients works the same way as having a single client.

quarkus.mongodb.connection-string = mongodb://login:pass@mongo1:27017/database

quarkus.mongodb.users.connection-string = mongodb://mongo2:27017/userdb
quarkus.mongodb.inventory.connection-string = mongodb://mongo3:27017/invdb,mongo4:27017/invdb

Notice there’s an extra bit in the key (the users and inventory segments). The syntax is as follows: quarkus.mongodb.[optional name.][mongo connection property]. If the name is omitted, it configures the default client.

The use of multiple MongoDB clients enables multi-tenancy for MongoDB by allowing to connect to multiple MongoDB clusters.
If you want to connect to multiple databases inside the same cluster, multiple clients are not necessary as a single client is able to access all databases in the same cluster (as a JDBC connection is able to access to multiple schemas inside the same database).

Named Mongo client Injection

When using multiple clients, each MongoClient, you can select the client to inject using the io.quarkus.mongodb.MongoClientName qualifier. Using the above properties to configure three different clients, you can also inject each one as follows:

@Inject
MongoClient defaultMongoClient;

@Inject
@MongoClientName("users")
MongoClient mongoClient1;

@Inject
@MongoClientName("inventory")
ReactiveMongoClient mongoClient2;

Running a MongoDB Database

As by default, MongoClient is configured to access a local MongoDB database on port 27017 (the default MongoDB port), if you have a local running database on this port, there is nothing more to do before being able to test it!

If you want to use Docker to run a MongoDB database, you can use the following command to launch one:

docker run -ti --rm -p 27017:27017 mongo:4.4

If you use Dev Services, launching the container manually is not necessary.

Creating a frontend

Now let’s add a simple web page to interact with our FruitResource. Quarkus automatically serves static resources located under the META-INF/resources directory. In the src/main/resources/META-INF/resources directory, add a fruits.html file with the content from this fruits.html file in it.

You can now interact with your REST service:

  • start Quarkus with:

    CLI
    quarkus dev
    Maven
    ./mvnw quarkus:dev
    Gradle
    ./gradlew --console=plain quarkusDev

  • open a browser to http://localhost:8080/fruits.html

  • add new fruits to the list via the form

Reactive MongoDB Client

A reactive MongoDB Client is included in Quarkus. Using it is as easy as using the classic MongoDB Client. You can rewrite the previous example to use it like the following.

Mutiny

The MongoDB reactive client uses Mutiny reactive types. If you are not familiar with Mutiny, check Mutiny - an intuitive reactive programming library.

 
package org.acme.mongodb;

import io.quarkus.mongodb.reactive.ReactiveMongoClient;
import io.quarkus.mongodb.reactive.ReactiveMongoCollection;
import io.smallrye.mutiny.Uni;
import org.bson.Document;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import java.util.List;

@ApplicationScoped
public class ReactiveFruitService {

    @Inject
    ReactiveMongoClient mongoClient;

    public Uni<List<Fruit>> list() {
        return getCollection().find()
                .map(doc -> {
                    Fruit fruit = new Fruit();
                    fruit.setName(doc.getString("name"));
                    fruit.setDescription(doc.getString("description"));
                    return fruit;
                }).collect().asList();
    }

    public Uni<Void> add(Fruit fruit) {
        Document document = new Document()
                .append("name", fruit.getName())
                .append("description", fruit.getDescription());
        return getCollection().insertOne(document)
                .onItem().ignore().andContinueWithNull();
    }

    private ReactiveMongoCollection<Document> getCollection() {
        return mongoClient.getDatabase("fruit").getCollection("fruit");
    }
}
package org.acme.mongodb;

import io.smallrye.mutiny.Uni;

import java.util.List;

import jakarta.inject.Inject;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.core.MediaType;

@Path("/reactive_fruits")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ReactiveFruitResource {

    @Inject
    ReactiveFruitService fruitService;

    @GET
    public Uni<List<Fruit>> list() {
        return fruitService.list();
    }

    @POST
    public Uni<List<Fruit>> add(Fruit fruit) {
        return fruitService.add(fruit)
                .onItem().ignore().andSwitchTo(this::list);
    }
}

Simplifying MongoDB Client usage using BSON codec

By using a Bson Codec, the MongoDB Client will take care of the transformation of your domain object to/from a MongoDB Document automatically.

First you need to create a Bson Codec that will tell Bson how to transform your entity to/from a MongoDB Document. Here we use a CollectibleCodec as our object is retrievable from the database (it has a MongoDB identifier), if not we would have used a Codec instead. More information in the codec documentation: https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/data-formats/codecs/.

package org.acme.mongodb.codec;

import com.mongodb.MongoClientSettings;
import org.acme.mongodb.Fruit;
import org.bson.Document;
import org.bson.BsonWriter;
import org.bson.BsonValue;
import org.bson.BsonReader;
import org.bson.BsonString;
import org.bson.codecs.Codec;
import org.bson.codecs.CollectibleCodec;
import org.bson.codecs.DecoderContext;
import org.bson.codecs.EncoderContext;

import java.util.UUID;

public class FruitCodec implements CollectibleCodec<Fruit> {

    private final Codec<Document> documentCodec;

    public FruitCodec() {
        this.documentCodec = MongoClientSettings.getDefaultCodecRegistry().get(Document.class);
    }

    @Override
    public void encode(BsonWriter writer, Fruit fruit, EncoderContext encoderContext) {
        Document doc = new Document();
        doc.put("name", fruit.getName());
        doc.put("description", fruit.getDescription());
        documentCodec.encode(writer, doc, encoderContext);
    }

    @Override
    public Class<Fruit> getEncoderClass() {
        return Fruit.class;
    }

    @Override
    public Fruit generateIdIfAbsentFromDocument(Fruit document) {
        if (!documentHasId(document)) {
            document.setId(UUID.randomUUID().toString());
        }
        return document;
    }

    @Override
    public boolean documentHasId(Fruit document) {
        return document.getId() != null;
    }

    @Override
    public BsonValue getDocumentId(Fruit document) {
        return new BsonString(document.getId());
    }

    @Override
    public Fruit decode(BsonReader reader, DecoderContext decoderContext) {
        Document document = documentCodec.decode(reader, decoderContext);
        Fruit fruit = new Fruit();
        if (document.getString("id") != null) {
            fruit.setId(document.getString("id"));
        }
        fruit.setName(document.getString("name"));
        fruit.setDescription(document.getString("description"));
        return fruit;
    }
}

Then you need to create a CodecProvider to link this Codec to the Fruit class.

package org.acme.mongodb.codec;

import org.acme.mongodb.Fruit;
import org.bson.codecs.Codec;
import org.bson.codecs.configuration.CodecProvider;
import org.bson.codecs.configuration.CodecRegistry;

public class FruitCodecProvider implements CodecProvider {
    @Override
    public <T> Codec<T> get(Class<T> clazz, CodecRegistry registry) {
        if (clazz.equals(Fruit.class)) {
            return (Codec<T>) new FruitCodec();
        }
        return null;
    }

}

Quarkus takes care of registering the CodecProvider for you as a CDI bean of @Singleton scope.

Finally, when getting the MongoCollection from the database you can use directly the Fruit class instead of the Document one, the codec will automatically map the Document to/from your Fruit class.

Here is an example of using a MongoCollection with the FruitCodec.

package org.acme.mongodb;

import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoCursor;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import java.util.ArrayList;
import java.util.List;

@ApplicationScoped
public class CodecFruitService {

    @Inject MongoClient mongoClient;

    public List<Fruit> list(){
        List<Fruit> list = new ArrayList<>();
        MongoCursor<Fruit> cursor = getCollection().find().iterator();

        try {
            while (cursor.hasNext()) {
                list.add(cursor.next());
            }
        } finally {
            cursor.close();
        }
        return list;
    }

    public void add(Fruit fruit){
        getCollection().insertOne(fruit);
    }

    private MongoCollection<Fruit> getCollection(){
        return mongoClient.getDatabase("fruit").getCollection("fruit", Fruit.class);
    }
}

The POJO Codec

The POJO Codec provides a set of annotations that enable the customization of the way a POJO is mapped to a MongoDB collection and this codec is initialized automatically by Quarkus. This codec also supports Java records so you can use them for your POJOs or an attribute of your POJOs.

One of these annotations is the @BsonDiscriminator annotation that allows to storage multiple Java types in a single MongoDB collection by adding a discriminator field inside the document. It can be useful when working with abstract types or interfaces.

Quarkus will automatically register all the classes annotated with @BsonDiscriminator with the POJO codec.

The POJO Codec have enhanced generic support via PropertyCodecProvider, Quarkus will automatically register any PropertyCodecProvider with the POJO Codec (these classes are automatically made CDI beans of @Singleton scope). When building native executables and using generic types, you might need to register the type arguments for reflection.

Simplifying MongoDB with Panache

The MongoDB with Panache extension facilitates the usage of MongoDB by providing active record style entities (and repositories) like you have in Hibernate ORM with Panache and focuses on making your entities trivial and fun to write in Quarkus.

Schema migration with Liquibase

The Liquibase MongoDB extension facilitates the initialization of a MongoDB database including indices and initial data. It implements the same schema migration facilities that Liquibase offers for SQL databases.

Connection Health Check

If you are using the quarkus-smallrye-health extension, quarkus-mongodb-client will automatically add a readiness health check to validate the connection to the cluster.

So when you access the /q/health/ready endpoint of your application you will have information about the connection validation status.

This behavior can be disabled by setting the quarkus.mongodb.health.enabled property to false in your application.properties.

Metrics

If you are using the quarkus-micrometer or quarkus-smallrye-metrics extension, quarkus-mongodb-client can provide metrics about the connection pools. This behavior must first be enabled by setting the quarkus.mongodb.metrics.enabled property to true in your application.properties.

So when you access the /q/metrics endpoint of your application you will have information about the connection pool status. When using SmallRye Metrics, connection pool metrics will be available under the vendor scope.

Tracing

To use tracing with MongoDB, you need to add the quarkus-opentelemetry extension to your project.

Even with all the tracing infrastructure in place the mongodb tracing is not enabled by default, and you need to enable it by setting this property:

# enable tracing
quarkus.mongodb.tracing.enabled=true

Testing helpers

Dev Services for MongoDB is your best option to start a MongoDB database for your unit tests.

But if you can’t use it, you can start a MongoDB database using one of the two QuarkusTestResourceLifecycleManager that Quarkus provides. They rely on Flapdoodle embedded MongoDB.

  • io.quarkus.test.mongodb.MongoTestResource will start a single instance on port 27017.

  • io.quarkus.test.mongodb.MongoReplicaSetTestResource will start a replicaset with two instances, one on port 27017 and the other on port 27018.

To use them, you need to add the io.quarkus:quarkus-test-mongodb dependency to your pom.xml.

For more information about the usage of a QuarkusTestResourceLifecycleManager please read Quarkus test resource.

To set the desired port MongoDB will listen to when it is launched, the following code should be used:

@QuarkusTestResource(value = MongoTestResource.class, initArgs = @ResourceArg(name = MongoTestResource.PORT, value = "27017"))

To set the desired MongoDB version that will be launched, the following code should be used:

@QuarkusTestResource(value = MongoTestResource.class, initArgs = @ResourceArg(name = MongoTestResource.VERSION, value = "V5_0"))

The string value used can be any of one of the de.flapdoodle.embed.mongo.distribution.Version or de.flapdoodle.embed.mongo.distribution.Version.Main enums. If no version is specified, Version.Main.V4_0 is used by default.

The legacy client

We don’t include the legacy MongoDB client by default. It contains the now retired MongoDB Java API (DB, DBCollection,…​ ) and the com.mongodb.MongoClient that is now superseded by com.mongodb.client.MongoClient.

If you want to use the legacy API, you need to add the following dependency to your build file:

pom.xml
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-legacy</artifactId>
</dependency>
build.gradle
implementation("org.mongodb:mongodb-driver-legacy")

Building a native executable

You can use the MongoDB client in a native executable.

If you want to use SSL/TLS encryption, you need to add these properties in your application.properties:

quarkus.mongodb.tls=true
quarkus.mongodb.tls-insecure=true # only if TLS certificate cannot be validated

You can then build a native executable with the usual command:

CLI
quarkus build --native
Maven
./mvnw install -Dnative
Gradle
./gradlew build -Dquarkus.native.enabled=true

Running it is as simple as executing ./target/mongodb-quickstart-1.0.0-SNAPSHOT-runner.

You can then point your browser to http://localhost:8080/fruits.html and use your application.

Currently, Quarkus doesn’t support Client-Side Field Level Encryption in native mode.

If you encounter the following error when running your application in native mode:
Failed to encode 'MyObject'. Encoding 'myVariable' errored with: Can’t find a codec for class org.acme.MyVariable.
This means that the org.acme.MyVariable class is not known to GraalVM, the remedy is to add the @RegisterForReflection annotation to your MyVariable class. More details about the @RegisterForReflection annotation can be found on the native application tips page.

Customize the Mongo client configuration programmatically

If you need to customize the Mongo client configuration programmatically, you need to implement the io.quarkus.mongodb.runtime.MongoClientCustomizer interface and expose it as a CDI application scoped bean:

@ApplicationScoped
public class MyCustomizer implements MongoClientCustomizer {

    @Override
    public MongoClientSettings.Builder customize(MongoClientSettings.Builder builder) {
        return builder.applicationName("my-app");
    }
}

The bean can customize a specific client using the @MongoClientName qualifier to indicate the client name. When there is no qualifier, it customizes the default client. At most one customizer can be used per client. If multiple customizers targeting the same client are detected, an exception is thrown at build time.

This feature can be used to configure client-side field level encryption (CSFLE). Follows the instructions from the Mongo web site to configure CSFLE:

@ApplicationScoped
public class MyCustomizer implements MongoClientCustomizer {
    @Override
    public MongoClientSettings.Builder customize(MongoClientSettings.Builder builder) {
        Map<String, Map<String, Object>> kmsProviders = getKmsProviders();
        String dek = getDataEncryptionKey();
        Map<String, BsonDocument> schema = getSchema(dek);

        Map<String, Object> extraOptions = new HashMap<>();
        extraOptions.put("cryptSharedLibPath", "<path to crypt shared library>");

        return builder.autoEncryptionSettings(AutoEncryptionSettings.builder()
                .keyVaultNamespace(KEY_VAULT_NAMESPACE)
                .kmsProviders(kmsProviders)
                .schemaMap(schemaMap)
                .extraOptions(extraOptions)
                .build());
    }
}
Client-side field level encryption, and feature relying on Mongo Crypt in general, are not supported in native mode.

Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.mongodb.health.enabled

Whether a health check is published in case the smallrye-health extension is present.

Environment variable: QUARKUS_MONGODB_HEALTH_ENABLED

Show more

boolean

true

quarkus.mongodb.metrics.enabled

Whether metrics are published in case a metrics extension is present.

Environment variable: QUARKUS_MONGODB_METRICS_ENABLED

Show more

boolean

false

quarkus.mongodb.force-default-clients

If set to true, the default clients will always be created even if there are no injection points that use them

Environment variable: QUARKUS_MONGODB_FORCE_DEFAULT_CLIENTS

Show more

boolean

false

quarkus.mongodb.tracing.enabled

Whether or not tracing spans of driver commands are sent in case the quarkus-opentelemetry extension is present.

Environment variable: QUARKUS_MONGODB_TRACING_ENABLED

Show more

boolean

false

quarkus.mongodb.connection-string

Configures the connection string. The format is: mongodb://[username:password@]host1[:port1][,host2[:port2],…​[,hostN[:portN]]][/[database.collection][?options]]

mongodb:// is a required prefix to identify that this is a string in the standard connection format.

username:password@ are optional. If given, the driver will attempt to log in to a database after connecting to a database server. For some authentication mechanisms, only the username is specified and the password is not, in which case the ":" after the username is left off as well.

host1 is the only required part of the connection string. It identifies a server address to connect to.

:portX is optional and defaults to :27017 if not provided.

/database is the name of the database to log in to and thus is only relevant if the username:password@ syntax is used. If not specified the admin database will be used by default.

?options are connection options. Note that if database is absent there is still a / required between the last host and the ? introducing the options. Options are name=value pairs and the pairs are separated by "&".

An alternative format, using the mongodb+srv protocol, is:

mongodb+srv://[username:password@]host[/[database][?options]]

  • mongodb+srv:// is a required prefix for this format.

  • username:password@ are optional. If given, the driver will attempt to login to a database after connecting to a database server. For some authentication mechanisms, only the username is specified and the password is not, in which case the ":" after the username is left off as well

  • host is the only required part of the URI. It identifies a single host name for which SRV records are looked up from a Domain Name Server after prefixing the host name with "_mongodb._tcp". The host/port for each SRV record becomes the seed list used to connect, as if each one were provided as host/port pair in a URI using the normal mongodb protocol.

  • /database is the name of the database to login to and thus is only relevant if the username:password@ syntax is used. If not specified the "admin" database will be used by default.

  • ?options are connection options. Note that if database is absent there is still a / required between the last host and the ? introducing the options. Options are name=value pairs and the pairs are separated by "&". Additionally with the mongodb+srv protocol, TXT records are looked up from a Domain Name Server for the given host, and the text value of each one is prepended to any options on the URI itself. Because the last specified value for any option wins, that means that options provided on the URI will override any that are provided via TXT records.

Environment variable: QUARKUS_MONGODB_CONNECTION_STRING

Show more

string

quarkus.mongodb.hosts

Configures the MongoDB server addressed (one if single mode). The addresses are passed as host:port.

Environment variable: QUARKUS_MONGODB_HOSTS

Show more

list of string

127.0.0.1:27017

quarkus.mongodb.database

Configure the database name.

Environment variable: QUARKUS_MONGODB_DATABASE

Show more

string

quarkus.mongodb.application-name

Configures the application name.

Environment variable: QUARKUS_MONGODB_APPLICATION_NAME

Show more

string

quarkus.mongodb.max-pool-size

Configures the maximum number of connections in the connection pool.

Environment variable: QUARKUS_MONGODB_MAX_POOL_SIZE

Show more

int

quarkus.mongodb.min-pool-size

Configures the minimum number of connections in the connection pool.

Environment variable: QUARKUS_MONGODB_MIN_POOL_SIZE

Show more

int

quarkus.mongodb.max-connection-idle-time

Maximum idle time of a pooled connection. A connection that exceeds this limit will be closed.

Environment variable: QUARKUS_MONGODB_MAX_CONNECTION_IDLE_TIME

Show more

Duration 

quarkus.mongodb.max-connection-life-time

Maximum lifetime of a pooled connection. A connection that exceeds this limit will be closed.

Environment variable: QUARKUS_MONGODB_MAX_CONNECTION_LIFE_TIME

Show more

Duration 

quarkus.mongodb.maintenance-frequency

Configures the time period between runs of the maintenance job.

Environment variable: QUARKUS_MONGODB_MAINTENANCE_FREQUENCY

Show more

Duration 

quarkus.mongodb.maintenance-initial-delay

Configures period of time to wait before running the first maintenance job on the connection pool.

Environment variable: QUARKUS_MONGODB_MAINTENANCE_INITIAL_DELAY

Show more

Duration 

quarkus.mongodb.connect-timeout

How long a connection can take to be opened before timing out.

Environment variable: QUARKUS_MONGODB_CONNECT_TIMEOUT

Show more

Duration 

quarkus.mongodb.read-timeout

How long a socket read can take before timing out.

Environment variable: QUARKUS_MONGODB_READ_TIMEOUT

Show more

Duration 

quarkus.mongodb.tls-insecure

If connecting with TLS, this option enables insecure TLS connections.

Environment variable: QUARKUS_MONGODB_TLS_INSECURE

Show more

boolean

false

quarkus.mongodb.tls

Whether to connect using TLS.

Environment variable: QUARKUS_MONGODB_TLS

Show more

boolean

false

quarkus.mongodb.replica-set-name

Implies that the hosts given are a seed list, and the driver will attempt to find all members of the set.

Environment variable: QUARKUS_MONGODB_REPLICA_SET_NAME

Show more

string

quarkus.mongodb.server-selection-timeout

How long the driver will wait for server selection to succeed before throwing an exception.

Environment variable: QUARKUS_MONGODB_SERVER_SELECTION_TIMEOUT

Show more

Duration 

quarkus.mongodb.local-threshold

When choosing among multiple MongoDB servers to send a request, the driver will only send that request to a server whose ping time is less than or equal to the server with the fastest ping time plus the local threshold.

Environment variable: QUARKUS_MONGODB_LOCAL_THRESHOLD

Show more

Duration 

quarkus.mongodb.heartbeat-frequency

The frequency that the driver will attempt to determine the current state of each server in the cluster.

Environment variable: QUARKUS_MONGODB_HEARTBEAT_FREQUENCY

Show more

Duration 

quarkus.mongodb.read-concern

Configures the read concern. Supported values are: local|majority|linearizable|snapshot|available

Environment variable: QUARKUS_MONGODB_READ_CONCERN

Show more

string

quarkus.mongodb.read-preference

Configures the read preference. Supported values are: primary|primaryPreferred|secondary|secondaryPreferred|nearest

Environment variable: QUARKUS_MONGODB_READ_PREFERENCE

Show more

string

quarkus.mongodb.health.database

The database used during the readiness health checks

Environment variable: QUARKUS_MONGODB_HEALTH_DATABASE

Show more

string

admin

quarkus.mongodb.uuid-representation

Configures the UUID representation to use when encoding instances of java.util.UUID and when decoding BSON binary values with subtype of 3.

Environment variable: QUARKUS_MONGODB_UUID_REPRESENTATION

Show more

unspecified, standard, c-sharp-legacy, java-legacy, python-legacy

quarkus.mongodb.dns.server-host

This property configures the DNS server. If the server is not set, it tries to read the first nameserver from /etc /resolv.conf (if the file exists), otherwise fallback to the default.

Environment variable: QUARKUS_MONGODB_DNS_SERVER_HOST

Show more

string

quarkus.mongodb.dns.server-port

This property configures the DNS server port.

Environment variable: QUARKUS_MONGODB_DNS_SERVER_PORT

Show more

int

53

quarkus.mongodb.dns.lookup-timeout

If native.dns.use-vertx-dns-resolver is set to true, this property configures the DNS lookup timeout duration.

Environment variable: QUARKUS_MONGODB_DNS_LOOKUP_TIMEOUT

Show more

Duration 

5S

quarkus.mongodb.dns.log-activity

This property enables the logging ot the DNS lookup. It can be useful to understand why the lookup fails.

Environment variable: QUARKUS_MONGODB_DNS_LOG_ACTIVITY

Show more

boolean

false

quarkus.mongodb."mongo-client-configs".connection-string

Configures the connection string. The format is: mongodb://[username:password@]host1[:port1][,host2[:port2],…​[,hostN[:portN]]][/[database.collection][?options]]

mongodb:// is a required prefix to identify that this is a string in the standard connection format.

username:password@ are optional. If given, the driver will attempt to log in to a database after connecting to a database server. For some authentication mechanisms, only the username is specified and the password is not, in which case the ":" after the username is left off as well.

host1 is the only required part of the connection string. It identifies a server address to connect to.

:portX is optional and defaults to :27017 if not provided.

/database is the name of the database to log in to and thus is only relevant if the username:password@ syntax is used. If not specified the admin database will be used by default.

?options are connection options. Note that if database is absent there is still a / required between the last host and the ? introducing the options. Options are name=value pairs and the pairs are separated by "&".

An alternative format, using the mongodb+srv protocol, is:

mongodb+srv://[username:password@]host[/[database][?options]]

  • mongodb+srv:// is a required prefix for this format.

  • username:password@ are optional. If given, the driver will attempt to login to a database after connecting to a database server. For some authentication mechanisms, only the username is specified and the password is not, in which case the ":" after the username is left off as well

  • host is the only required part of the URI. It identifies a single host name for which SRV records are looked up from a Domain Name Server after prefixing the host name with "_mongodb._tcp". The host/port for each SRV record becomes the seed list used to connect, as if each one were provided as host/port pair in a URI using the normal mongodb protocol.

  • /database is the name of the database to login to and thus is only relevant if the username:password@ syntax is used. If not specified the "admin" database will be used by default.

  • ?options are connection options. Note that if database is absent there is still a / required between the last host and the ? introducing the options. Options are name=value pairs and the pairs are separated by "&". Additionally with the mongodb+srv protocol, TXT records are looked up from a Domain Name Server for the given host, and the text value of each one is prepended to any options on the URI itself. Because the last specified value for any option wins, that means that options provided on the URI will override any that are provided via TXT records.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__CONNECTION_STRING

Show more

string

quarkus.mongodb."mongo-client-configs".hosts

Configures the MongoDB server addressed (one if single mode). The addresses are passed as host:port.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__HOSTS

Show more

list of string

127.0.0.1:27017

quarkus.mongodb."mongo-client-configs".database

Configure the database name.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__DATABASE

Show more

string

quarkus.mongodb."mongo-client-configs".application-name

Configures the application name.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__APPLICATION_NAME

Show more

string

quarkus.mongodb."mongo-client-configs".max-pool-size

Configures the maximum number of connections in the connection pool.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__MAX_POOL_SIZE

Show more

int

quarkus.mongodb."mongo-client-configs".min-pool-size

Configures the minimum number of connections in the connection pool.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__MIN_POOL_SIZE

Show more

int

quarkus.mongodb."mongo-client-configs".max-connection-idle-time

Maximum idle time of a pooled connection. A connection that exceeds this limit will be closed.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__MAX_CONNECTION_IDLE_TIME

Show more

Duration 

quarkus.mongodb."mongo-client-configs".max-connection-life-time

Maximum lifetime of a pooled connection. A connection that exceeds this limit will be closed.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__MAX_CONNECTION_LIFE_TIME

Show more

Duration 

quarkus.mongodb."mongo-client-configs".maintenance-frequency

Configures the time period between runs of the maintenance job.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__MAINTENANCE_FREQUENCY

Show more

Duration 

quarkus.mongodb."mongo-client-configs".maintenance-initial-delay

Configures period of time to wait before running the first maintenance job on the connection pool.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__MAINTENANCE_INITIAL_DELAY

Show more

Duration 

quarkus.mongodb."mongo-client-configs".connect-timeout

How long a connection can take to be opened before timing out.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__CONNECT_TIMEOUT

Show more

Duration 

quarkus.mongodb."mongo-client-configs".read-timeout

How long a socket read can take before timing out.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__READ_TIMEOUT

Show more

Duration 

quarkus.mongodb."mongo-client-configs".tls-insecure

If connecting with TLS, this option enables insecure TLS connections.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__TLS_INSECURE

Show more

boolean

false

quarkus.mongodb."mongo-client-configs".tls

Whether to connect using TLS.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__TLS

Show more

boolean

false

quarkus.mongodb."mongo-client-configs".replica-set-name

Implies that the hosts given are a seed list, and the driver will attempt to find all members of the set.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__REPLICA_SET_NAME

Show more

string

quarkus.mongodb."mongo-client-configs".server-selection-timeout

How long the driver will wait for server selection to succeed before throwing an exception.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__SERVER_SELECTION_TIMEOUT

Show more

Duration 

quarkus.mongodb."mongo-client-configs".local-threshold

When choosing among multiple MongoDB servers to send a request, the driver will only send that request to a server whose ping time is less than or equal to the server with the fastest ping time plus the local threshold.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__LOCAL_THRESHOLD

Show more

Duration 

quarkus.mongodb."mongo-client-configs".heartbeat-frequency

The frequency that the driver will attempt to determine the current state of each server in the cluster.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__HEARTBEAT_FREQUENCY

Show more

Duration 

quarkus.mongodb."mongo-client-configs".read-concern

Configures the read concern. Supported values are: local|majority|linearizable|snapshot|available

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__READ_CONCERN

Show more

string

quarkus.mongodb."mongo-client-configs".read-preference

Configures the read preference. Supported values are: primary|primaryPreferred|secondary|secondaryPreferred|nearest

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__READ_PREFERENCE

Show more

string

quarkus.mongodb."mongo-client-configs".health.database

The database used during the readiness health checks

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__HEALTH_DATABASE

Show more

string

admin

quarkus.mongodb."mongo-client-configs".uuid-representation

Configures the UUID representation to use when encoding instances of java.util.UUID and when decoding BSON binary values with subtype of 3.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__UUID_REPRESENTATION

Show more

unspecified, standard, c-sharp-legacy, java-legacy, python-legacy

Dev Services

Type

Default

quarkus.mongodb.devservices.enabled

If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present.

When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode.

Environment variable: QUARKUS_MONGODB_DEVSERVICES_ENABLED

Show more

boolean

quarkus.mongodb.devservices.image-name

The container image name to use, for container based DevServices providers.

Environment variable: QUARKUS_MONGODB_DEVSERVICES_IMAGE_NAME

Show more

string

quarkus.mongodb.devservices.port

Optional fixed port the dev service will listen to.

If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_MONGODB_DEVSERVICES_PORT

Show more

int

quarkus.mongodb.devservices.properties."property-key"

Generic properties that are added to the connection URL.

Environment variable: QUARKUS_MONGODB_DEVSERVICES_PROPERTIES__PROPERTY_KEY_

Show more

Map<String,String>

quarkus.mongodb.devservices.container-env."environment-variable-name"

Environment variables that are passed to the container.

Environment variable: QUARKUS_MONGODB_DEVSERVICES_CONTAINER_ENV__ENVIRONMENT_VARIABLE_NAME_

Show more

Map<String,String>

quarkus.mongodb.devservices.shared

Indicates if the MongoDB server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for MongoDB starts a new container.

The discovery uses the quarkus-dev-service-mongodb label. The value is configured using the service-name property.

Container sharing is only used in dev mode.

Environment variable: QUARKUS_MONGODB_DEVSERVICES_SHARED

Show more

boolean

true

quarkus.mongodb.devservices.service-name

The value of the quarkus-dev-service-mongodb label attached to the started container. This property is used when shared is set to true. In this case, before starting a container, Dev Services for MongoDB looks for a container with the quarkus-dev-service-mongodb label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise it starts a new container with the quarkus-dev-service-mongodb label set to the specified value.

Environment variable: QUARKUS_MONGODB_DEVSERVICES_SERVICE_NAME

Show more

string

mongodb

Write concern

Type

Default

quarkus.mongodb.write-concern.safe

Configures the safety. If set to true: the driver ensures that all writes are acknowledged by the MongoDB server, or else throws an exception. (see also w and wtimeoutMS). If set fo - false: the driver does not ensure that all writes are acknowledged by the MongoDB server.

Environment variable: QUARKUS_MONGODB_WRITE_CONCERN_SAFE

Show more

boolean

true

quarkus.mongodb.write-concern.journal

Configures the journal writing aspect. If set to true: the driver waits for the server to group commit to the journal file on disk. If set to false: the driver does not wait for the server to group commit to the journal file on disk.

Environment variable: QUARKUS_MONGODB_WRITE_CONCERN_JOURNAL

Show more

boolean

true

quarkus.mongodb.write-concern.w

When set, the driver adds w: wValue to all write commands. It requires safe to be true. The value is typically a number, but can also be the majority string.

Environment variable: QUARKUS_MONGODB_WRITE_CONCERN_W

Show more

string

quarkus.mongodb.write-concern.retry-writes

If set to true, the driver will retry supported write operations if they fail due to a network error.

Environment variable: QUARKUS_MONGODB_WRITE_CONCERN_RETRY_WRITES

Show more

boolean

false

quarkus.mongodb.write-concern.w-timeout

When set, the driver adds wtimeout : ms to all write commands. It requires safe to be true.

Environment variable: QUARKUS_MONGODB_WRITE_CONCERN_W_TIMEOUT

Show more

Duration 

Credentials and authentication mechanism

Type

Default

quarkus.mongodb.credentials.username

Configures the username.

Environment variable: QUARKUS_MONGODB_CREDENTIALS_USERNAME

Show more

string

quarkus.mongodb.credentials.password

Configures the password.

Environment variable: QUARKUS_MONGODB_CREDENTIALS_PASSWORD

Show more

string

quarkus.mongodb.credentials.auth-mechanism

Configures the authentication mechanism to use if a credential was supplied. The default is unspecified, in which case the client will pick the most secure mechanism available based on the sever version. For the GSSAPI and MONGODB-X509 mechanisms, no password is accepted, only the username. Supported values: null or GSSAPI|PLAIN|MONGODB-X509|SCRAM_SHA_1|SCRAM_SHA_256|MONGODB_AWS

Environment variable: QUARKUS_MONGODB_CREDENTIALS_AUTH_MECHANISM

Show more

string

quarkus.mongodb.credentials.auth-source

Configures the source of the authentication credentials. This is typically the database where the credentials have been created. The value defaults to the database specified in the path portion of the connection string or in the 'database' configuration property. If the database is specified in neither place, the default value is admin. This option is only respected when using the MONGO-CR mechanism (the default).

Environment variable: QUARKUS_MONGODB_CREDENTIALS_AUTH_SOURCE

Show more

string

quarkus.mongodb.credentials.auth-mechanism-properties."property-key"

Allows passing authentication mechanism properties.

Environment variable: QUARKUS_MONGODB_CREDENTIALS_AUTH_MECHANISM_PROPERTIES__PROPERTY_KEY_

Show more

Map<String,String>

quarkus.mongodb.credentials.credentials-provider

The credentials provider name

Environment variable: QUARKUS_MONGODB_CREDENTIALS_CREDENTIALS_PROVIDER

Show more

string

quarkus.mongodb.credentials.credentials-provider-name

The credentials provider bean name.

This is a bean name (as in @Named) of a bean that implements CredentialsProvider. It is used to select the credentials provider bean when multiple exist. This is unnecessary when there is only one credentials provider available.

For Vault, the credentials provider bean name is vault-credentials-provider.

Environment variable: QUARKUS_MONGODB_CREDENTIALS_CREDENTIALS_PROVIDER_NAME

Show more

string

Write concern

Type

Default

quarkus.mongodb."mongo-client-configs".write-concern.safe

Configures the safety. If set to true: the driver ensures that all writes are acknowledged by the MongoDB server, or else throws an exception. (see also w and wtimeoutMS). If set fo - false: the driver does not ensure that all writes are acknowledged by the MongoDB server.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__WRITE_CONCERN_SAFE

Show more

boolean

true

quarkus.mongodb."mongo-client-configs".write-concern.journal

Configures the journal writing aspect. If set to true: the driver waits for the server to group commit to the journal file on disk. If set to false: the driver does not wait for the server to group commit to the journal file on disk.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__WRITE_CONCERN_JOURNAL

Show more

boolean

true

quarkus.mongodb."mongo-client-configs".write-concern.w

When set, the driver adds w: wValue to all write commands. It requires safe to be true. The value is typically a number, but can also be the majority string.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__WRITE_CONCERN_W

Show more

string

quarkus.mongodb."mongo-client-configs".write-concern.retry-writes

If set to true, the driver will retry supported write operations if they fail due to a network error.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__WRITE_CONCERN_RETRY_WRITES

Show more

boolean

false

quarkus.mongodb."mongo-client-configs".write-concern.w-timeout

When set, the driver adds wtimeout : ms to all write commands. It requires safe to be true.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__WRITE_CONCERN_W_TIMEOUT

Show more

Duration 

Credentials and authentication mechanism

Type

Default

quarkus.mongodb."mongo-client-configs".credentials.username

Configures the username.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__CREDENTIALS_USERNAME

Show more

string

quarkus.mongodb."mongo-client-configs".credentials.password

Configures the password.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__CREDENTIALS_PASSWORD

Show more

string

quarkus.mongodb."mongo-client-configs".credentials.auth-mechanism

Configures the authentication mechanism to use if a credential was supplied. The default is unspecified, in which case the client will pick the most secure mechanism available based on the sever version. For the GSSAPI and MONGODB-X509 mechanisms, no password is accepted, only the username. Supported values: null or GSSAPI|PLAIN|MONGODB-X509|SCRAM_SHA_1|SCRAM_SHA_256|MONGODB_AWS

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__CREDENTIALS_AUTH_MECHANISM

Show more

string

quarkus.mongodb."mongo-client-configs".credentials.auth-source

Configures the source of the authentication credentials. This is typically the database where the credentials have been created. The value defaults to the database specified in the path portion of the connection string or in the 'database' configuration property. If the database is specified in neither place, the default value is admin. This option is only respected when using the MONGO-CR mechanism (the default).

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__CREDENTIALS_AUTH_SOURCE

Show more

string

quarkus.mongodb."mongo-client-configs".credentials.auth-mechanism-properties."property-key"

Allows passing authentication mechanism properties.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__CREDENTIALS_AUTH_MECHANISM_PROPERTIES__PROPERTY_KEY_

Show more

Map<String,String>

quarkus.mongodb."mongo-client-configs".credentials.credentials-provider

The credentials provider name

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__CREDENTIALS_CREDENTIALS_PROVIDER

Show more

string

quarkus.mongodb."mongo-client-configs".credentials.credentials-provider-name

The credentials provider bean name.

This is a bean name (as in @Named) of a bean that implements CredentialsProvider. It is used to select the credentials provider bean when multiple exist. This is unnecessary when there is only one credentials provider available.

For Vault, the credentials provider bean name is vault-credentials-provider.

Environment variable: QUARKUS_MONGODB__MONGO_CLIENT_CONFIGS__CREDENTIALS_CREDENTIALS_PROVIDER_NAME

Show more

string
About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with P.

Related content

On the same extensions

On the same topics

Quarkus is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license.

This website was built with Jekyll, is hosted on GitHub Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

Navigation
Follow Us
Get Help
Languages
Quarkus is made of community projects
CC by 3.0 | Privacy Policy Sponsored by