Support runtime active / inactive Mongo Clients

Author: radcortez

docs/src/main/asciidoc/mongodb.adoc

@@ -303,6 +303,71 @@ MongoClient mongoClient1;
 ReactiveMongoClient mongoClient2;
 ----
 
+=== Activate or deactivate Mongo Clients
+
+When a Mongo Client is configured at build time, and its URL is set at runtime, it is active by default. Quarkus
+starts the corresponding Mongo Client when the application starts.
+
+To deactivate a Mongo Client at runtime, either:
+
+* Do not set `quarkus.mongodb[.optional name].hosts` or `quarkus.mongodb[.optional name].connection-#string#`.
+* Set `quarkus.mongodb[.optional name].active` to `false`.
+
+If a Mongo Client is not active:
+
+* The Mongo Client does not attempt to connect to Mongo during application startup.
+* The Mongo Client does not contribute a <<mongo-health-check,health check>>.
+* Static CDI injection points involving the Mongo Client, such as `@Inject ReactiveMongoClient mongoClient` or `@Inject MongoClient mongoClient`, cause application startup to fail.
+* Dynamic retrieval of the Mongo Client, such as through `CDI.getBeanContainer()`, `Arc.instance()`, or an injected `Instance<ReactiveMongoClient>`, causes an exception to be thrown.
+* Other Quarkus extensions that consume the Mongo Client may cause application startup to fail.
+
+This feature is especially useful when the application must dynamically select a Mongo Client from a predefined set at
+runtime.
+
+.An example of configuring multiple Mongo Clients for runtime selection:
+
+[source,properties]
+----
+quarkus.mongodb.one.active=false
+quarkus.mongodb.one.connection-string=mongodb://127.0.0.1:27018
+quarkus.mongodb.two.active=false
+quarkus.mongodb.two.connection-string=mongodb://127.0.0.1:27019
+----
+
+[source,java]
+----
+import io.quarkus.arc.InjectableInstance;
+
+import com.mongodb.client.MongoClient;
+import io.quarkus.mongodb.reactive.ReactiveMongoClient;
+
+@ApplicationScoped
+public class MyConsumer {
+    @Inject
+    @MongoClientName("one")
+    InjectableInstance<ReactiveMongoClient> one;
+    @Inject
+    @MongoClientName("two")
+    InjectableInstance<MongoClient> two;
+    public void doSomething() {
+        ReactiveMongoClient mongoClient = one.getActive();
+        // ...
+    }
+}
+----
+
+Setting `quarkus.mongodb.one.active=true` xref:config-reference.adoc#configuration-sources[at runtime] makes only the
+Mongo Client `one` available.
+Setting `quarkus.mongodb.two.active=true` at runtime makes only the Mongo Client `two` available.
+
+[IMPORTANT]
+====
+A Mongo Client (either default or named) must always be discoverable at build-time to be considered for runtime
+injection. This can be done by injecting the Mongo Client name with `@MongoClientName`. If the Mongo Client name may be
+active or inactive, it needs to use the wrapper `InjectableInstance<>`, or else Quarkus will throw an exception at
+startup time if the Mongo Client is inactive. Alternatively, Mongo Clients may also be discovered via configuration.
+====
+
 == 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!
 
@@ -605,6 +670,7 @@ The xref:mongodb-panache.adoc[MongoDB with Panache] extension facilitates the us
 The xref:liquibase-mongodb.adoc[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.
 
+[[mongo-health-check]]
 == Connection Health Check
 
 If you are using the `quarkus-smallrye-health` extension, `quarkus-mongodb-client` will automatically add a readiness health check

extensions/liquibase/liquibase-mongodb/runtime/src/main/java/io/quarkus/liquibase/mongodb/LiquibaseMongodbFactory.java

@@ -146,7 +146,7 @@ public Liquibase createLiquibase() {
 
     private Database createDatabase(MongoClients clients, String clientName, String databaseName) {
         MongoConnection databaseConnection = new MongoConnection();
-        MongoClient mongoClient = clients.createMongoClient(clientName);
+        MongoClient mongoClient = clients.unmanagedMongoClient(clientName);
         databaseConnection.setMongoClient(mongoClient);
         databaseConnection.setMongoDatabase(mongoClient.getDatabase(databaseName));
         Database database = new MongoLiquibaseDatabase();

extensions/mongodb-client/deployment/src/main/java/io/quarkus/mongodb/deployment/MongoClientProcessor.java

@@ -397,9 +397,9 @@ private SyntheticBeanBuildItem createBlockingSyntheticBean(MongoClientRecorder r
         SyntheticBeanBuildItem.ExtendedBeanConfigurator configurator = SyntheticBeanBuildItem
                 .configure(MongoClient.class)
                 .scope(ApplicationScoped.class)
-                // pass the runtime config into the recorder to ensure that the DataSource related beans
-                // are created after runtime configuration has been set up
                 .supplier(recorder.mongoClientSupplier(clientName))
+                .checkActive(recorder.checkActive(clientName))
+                .startup()
                 .setRuntimeInit();
 
         return applyCommonBeanConfig(makeUnremovable, clientName, addMongoClientQualifier, configurator, false);
@@ -411,9 +411,9 @@ private SyntheticBeanBuildItem createReactiveSyntheticBean(MongoClientRecorder r
         SyntheticBeanBuildItem.ExtendedBeanConfigurator configurator = SyntheticBeanBuildItem
                 .configure(ReactiveMongoClient.class)
                 .scope(ApplicationScoped.class)
-                // pass the runtime config into the recorder to ensure that the DataSource related beans
-                // are created after runtime configuration has been set up
                 .supplier(recorder.reactiveMongoClientSupplier(clientName))
+                .checkActive(recorder.checkActive(clientName))
+                .startup()
                 .setRuntimeInit();
 
         return applyCommonBeanConfig(makeUnremovable, clientName, addMongoClientQualifier, configurator, true);

extensions/mongodb-client/deployment/src/test/java/io/quarkus/mongodb/MongoActiveClientsMissingConfigTest.java

@@ -0,0 +1,48 @@
+package io.quarkus.mongodb;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import jakarta.inject.Inject;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.DisabledOnOs;
+import org.junit.jupiter.api.condition.OS;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import com.mongodb.client.MongoClient;
+
+import io.quarkus.arc.InactiveBeanException;
+import io.quarkus.mongodb.reactive.ReactiveMongoClient;
+import io.quarkus.test.QuarkusUnitTest;
+
+@DisabledOnOs(value = OS.WINDOWS, disabledReason = "Flapdoodle doesn't work very well on Windows with replicas")
+public class MongoActiveClientsMissingConfigTest {
+    @RegisterExtension
+    static final QuarkusUnitTest unitTest = new QuarkusUnitTest()
+            .withApplicationRoot((jar) -> jar.addClasses(MongoTestBase.class))
+            .overrideRuntimeConfigKey("quarkus.mongodb.active.hosts", "")
+            .overrideRuntimeConfigKey("quarkus.mongodb.active.connection-string", "")
+            .assertException(e -> assertThat(e)// Can't use isInstanceOf due to weird classloading in tests
+                    .satisfies(t -> assertThat(t.getClass().getName()).isEqualTo(InactiveBeanException.class.getName()))
+                    .hasMessageContainingAll(
+                            """
+                                    Mongo Client 'active' was deactivated automatically because neither the \
+                                    hosts nor the connectionString is set. \
+                                    To activate the Mongo Client, set the configuration property 'quarkus.mongodb.active.hosts' \
+                                    or 'quarkus.mongodb.active.connection-string' \
+                                    Refer to https://quarkus.io/guides/mongodb for guidance.
+                                    """));
+
+    @Inject
+    @MongoClientName("active")
+    MongoClient mongoClient;
+    @Inject
+    @MongoClientName("active")
+    ReactiveMongoClient reactiveMongoClient;
+
+    @Test
+    void missingConfig() {
+        Assertions.fail();
+    }
+}

extensions/mongodb-client/deployment/src/test/java/io/quarkus/mongodb/MongoActiveClientsTest.java

@@ -0,0 +1,55 @@
+package io.quarkus.mongodb;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import jakarta.enterprise.inject.Any;
+import jakarta.inject.Inject;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.DisabledOnOs;
+import org.junit.jupiter.api.condition.OS;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import com.mongodb.client.MongoClient;
+
+import io.quarkus.arc.InjectableInstance;
+import io.quarkus.mongodb.reactive.ReactiveMongoClient;
+import io.quarkus.test.QuarkusUnitTest;
+
+@DisabledOnOs(value = OS.WINDOWS, disabledReason = "Flapdoodle doesn't work very well on Windows with replicas")
+public class MongoActiveClientsTest extends MongoWithReplicasTestBase {
+    @RegisterExtension
+    static final QuarkusUnitTest unitTest = new QuarkusUnitTest()
+            .withApplicationRoot((jar) -> jar.addClasses(MongoTestBase.class));
+
+    @Inject
+    InjectableInstance<MongoClient> mongoClient;
+    @Inject
+    InjectableInstance<ReactiveMongoClient> reactiveMongoClient;
+
+    @Inject
+    @MongoClientName("active")
+    InjectableInstance<MongoClient> activeMongoClient;
+    @Inject
+    @MongoClientName("active")
+    InjectableInstance<ReactiveMongoClient> activeReactiveMongoClient;
+
+    @Inject
+    @Any
+    InjectableInstance<MongoClient> all;
+    @Inject
+    @Any
+    InjectableInstance<ReactiveMongoClient> allReactive;
+
+    @Test
+    void inactiveClients() {
+        assertEquals(1, mongoClient.listActive().size());
+        assertEquals(1, reactiveMongoClient.listActive().size());
+
+        assertEquals(1, activeMongoClient.listActive().size());
+        assertEquals(1, activeReactiveMongoClient.listActive().size());
+
+        assertEquals(2, all.listActive().size());
+        assertEquals(2, allReactive.listActive().size());
+    }
+}

extensions/mongodb-client/deployment/src/test/java/io/quarkus/mongodb/MongoInactiveClientsByConfigExceptionTest.java

@@ -0,0 +1,46 @@
+package io.quarkus.mongodb;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import jakarta.inject.Inject;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.DisabledOnOs;
+import org.junit.jupiter.api.condition.OS;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import com.mongodb.client.MongoClient;
+
+import io.quarkus.arc.InactiveBeanException;
+import io.quarkus.mongodb.reactive.ReactiveMongoClient;
+import io.quarkus.test.QuarkusUnitTest;
+
+@DisabledOnOs(value = OS.WINDOWS, disabledReason = "Flapdoodle doesn't work very well on Windows with replicas")
+public class MongoInactiveClientsByConfigExceptionTest {
+    @RegisterExtension
+    static final QuarkusUnitTest unitTest = new QuarkusUnitTest()
+            .withApplicationRoot((jar) -> jar.addClasses(MongoTestBase.class))
+            .overrideRuntimeConfigKey("quarkus.mongodb.active.active", "false")
+            .assertException(e -> assertThat(e)// Can't use isInstanceOf due to weird classloading in tests
+                    .satisfies(t -> assertThat(t.getClass().getName()).isEqualTo(InactiveBeanException.class.getName()))
+                    .hasMessageContainingAll(
+                            """
+                                    Mongo Client 'active' was deactivated through configuration properties. \
+                                    To activate the Mongo Client, set configuration property \
+                                    'quarkus.mongodb.active.active' to 'true' and configure the Mongo Client 'active'. \
+                                    Refer to https://quarkus.io/guides/mongodb for guidance.
+                                    """));
+
+    @Inject
+    @MongoClientName("active")
+    MongoClient mongoClient;
+    @Inject
+    @MongoClientName("active")
+    ReactiveMongoClient reactiveMongoClient;
+
+    @Test
+    void inactive() {
+        Assertions.fail();
+    }
+}

extensions/mongodb-client/deployment/src/test/java/io/quarkus/mongodb/MongoInactiveClientsByConfigTest.java

@@ -0,0 +1,37 @@
+package io.quarkus.mongodb;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import jakarta.inject.Inject;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.DisabledOnOs;
+import org.junit.jupiter.api.condition.OS;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import com.mongodb.client.MongoClient;
+
+import io.quarkus.arc.InjectableInstance;
+import io.quarkus.mongodb.reactive.ReactiveMongoClient;
+import io.quarkus.test.QuarkusUnitTest;
+
+@DisabledOnOs(value = OS.WINDOWS, disabledReason = "Flapdoodle doesn't work very well on Windows with replicas")
+public class MongoInactiveClientsByConfigTest extends MongoWithReplicasTestBase {
+    @RegisterExtension
+    static final QuarkusUnitTest unitTest = new QuarkusUnitTest()
+            .withApplicationRoot((jar) -> jar.addClasses(MongoTestBase.class))
+            .overrideRuntimeConfigKey("quarkus.mongodb.inactive.active", "false");
+
+    @Inject
+    @MongoClientName("inactive")
+    InjectableInstance<MongoClient> mongoClient;
+    @Inject
+    @MongoClientName("inactive")
+    InjectableInstance<ReactiveMongoClient> reactiveMongoClient;
+
+    @Test
+    void inactiveClients() {
+        assertEquals(0, mongoClient.listActive().size());
+        assertEquals(0, reactiveMongoClient.listActive().size());
+    }
+}

extensions/mongodb-client/deployment/src/test/java/io/quarkus/mongodb/MongoInactiveClientsTest.java

@@ -0,0 +1,38 @@
+package io.quarkus.mongodb;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import jakarta.inject.Inject;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.DisabledOnOs;
+import org.junit.jupiter.api.condition.OS;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import com.mongodb.client.MongoClient;
+
+import io.quarkus.arc.InjectableInstance;
+import io.quarkus.mongodb.reactive.ReactiveMongoClient;
+import io.quarkus.test.QuarkusUnitTest;
+
+@DisabledOnOs(value = OS.WINDOWS, disabledReason = "Flapdoodle doesn't work very well on Windows with replicas")
+public class MongoInactiveClientsTest extends MongoWithReplicasTestBase {
+    @RegisterExtension
+    static final QuarkusUnitTest unitTest = new QuarkusUnitTest()
+            .withApplicationRoot((jar) -> jar.addClasses(MongoTestBase.class))
+            .overrideRuntimeConfigKey("quarkus.mongodb.inactive.hosts", "")
+            .overrideRuntimeConfigKey("quarkus.mongodb.inactive.connection-string", "");
+
+    @Inject
+    @MongoClientName("inactive")
+    InjectableInstance<MongoClient> mongoClient;
+    @Inject
+    @MongoClientName("inactive")
+    InjectableInstance<ReactiveMongoClient> reactiveMongoClient;
+
+    @Test
+    void inactiveClients() {
+        assertEquals(0, mongoClient.listActive().size());
+        assertEquals(0, reactiveMongoClient.listActive().size());
+    }
+}

extensions/mongodb-client/deployment/src/test/java/io/quarkus/mongodb/MongoMetricsTest.java

@@ -38,12 +38,8 @@ void cleanup() {
 
     @Test
     void testMetricsInitialization() {
-        // Clients are created lazily, this metric should not be present yet
-        assertThat(getMetric("mongodb.driver.pool.size")).isNull();
-        assertThat(getMetric("mongodb.driver.pool.checkedout")).isNull();
-
         // Just need to execute something so that a connection is opened
-        String name = client.listDatabaseNames().first();
+        client.listDatabaseNames().first();
 
         assertThat(getMetric("mongodb.driver.pool.size")).isOne();
         assertThat(getMetric("mongodb.driver.commands")).isOne();