From 100b44e1e49f24bbc501b7c370924df5c65b3c5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Mathieu?= Date: Thu, 8 Sep 2022 10:05:48 +0200 Subject: [PATCH] Improve MongoDB guides --- docs/src/main/asciidoc/mongodb-panache.adoc | 19 +++++++++------- docs/src/main/asciidoc/mongodb.adoc | 24 ++++++++++----------- 2 files changed, 23 insertions(+), 20 deletions(-) diff --git a/docs/src/main/asciidoc/mongodb-panache.adoc b/docs/src/main/asciidoc/mongodb-panache.adoc index 85021847c6130..1f62b79f0f368 100644 --- a/docs/src/main/asciidoc/mongodb-panache.adoc +++ b/docs/src/main/asciidoc/mongodb-panache.adoc @@ -7,9 +7,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc include::./attributes.adoc[] :config-file: application.properties -:mongodb-doc-root-url: https://mongodb.github.io/mongo-java-driver/4.2 +:mongodb-doc-root-url: https://www.mongodb.com/docs/drivers/java/sync/current -MongoDB is a well known NoSQL Database that is widely used, but using its raw API can be cumbersome as you need to express your entities and your queries as a MongoDB link:{mongodb-doc-root-url}/bson/documents/#document[`Document`]. +MongoDB is a well known NoSQL Database that is widely used, but using its raw API can be cumbersome as you need to express your entities and your queries as a MongoDB link:{mongodb-doc-root-url}/fundamentals/data-formats/documents/#document[`Document`]. MongoDB with Panache provides active record style entities (and repositories) like you have in xref:hibernate-orm-panache.adoc[Hibernate ORM with Panache] and focuses on making your entities trivial and fun to write in Quarkus. @@ -169,7 +169,7 @@ public class Person extends PanacheMongoEntity { NOTE: Annotating with `@MongoEntity` is optional. Here the entity will be stored in the `ThePerson` collection instead of the default `Person` collection. -MongoDB with Panache uses the link:{mongodb-doc-root-url}/bson/pojos/[PojoCodecProvider] to convert your entities to a MongoDB `Document`. +MongoDB with Panache uses the link:{mongodb-doc-root-url}/fundamentals/data-formats/document-data-format-pojo[PojoCodecProvider] to convert your entities to a MongoDB `Document`. You will be allowed to use the following annotations to customize this mapping: @@ -319,7 +319,7 @@ public class Person { NOTE: Annotating with `@MongoEntity` is optional. Here the entity will be stored in the `ThePerson` collection instead of the default `Person` collection. -MongoDB with Panache uses the link:{mongodb-doc-root-url}/bson/pojos/[PojoCodecProvider] to convert your entities to a MongoDB `Document`. +MongoDB with Panache uses the link:{mongodb-doc-root-url}/fundamentals/data-formats/document-data-format-pojo/[PojoCodecProvider] to convert your entities to a MongoDB `Document`. You will be allowed to use the following annotations to customize this mapping: @@ -746,7 +746,7 @@ quarkus.log.category."io.quarkus.mongodb.panache.runtime".level=DEBUG == The PojoCodecProvider: easy object to BSON document conversion. -MongoDB with Panache uses the link:{mongodb-doc-root-url}/bson/pojos[PojoCodecProvider], with link:{mongodb-doc-root-url}/pojos/#pojo-support[automatic POJO support], +MongoDB with Panache uses the link:{mongodb-doc-root-url}/fundamentals/data-formats/document-data-format-pojo/[PojoCodecProvider], with link:{mongodb-doc-root-url}/fundamentals/data-formats/document-data-format-pojo/#configure-the-driver-for-pojos[automatic POJO support], to automatically convert your object to a BSON document. In case you encounter the `org.bson.codecs.configuration.CodecConfigurationException` exception, it means the codec is not able to @@ -765,6 +765,9 @@ MongoDB offers ACID transactions since version 4.0. To use them with MongoDB with Panache you need to annotate the method that starts the transaction with the `@Transactional` annotation. +In MongoDB, a transaction is only possible on a replicaset, +luckily our xref:mongodb.adoc#dev-services[Dev Services for MongoDB] setups a single node replicaset so it is compatible with transactions. + WARNING: Transaction support inside MongoDB with Panache is still experimental. == Custom IDs @@ -829,7 +832,7 @@ Kotlin data classes are a very convenient way of defining data carrier classes, But this type of class comes with some limitations: all fields needs to be initialized at construction time or be marked as nullable, and the generated constructor needs to have as parameters all the fields of the data class. -MongoDB with Panache uses the link:{mongodb-doc-root-url}/bson/pojos[PojoCodecProvider], a MongoDB codec which mandates the presence of a parameterless constructor. +MongoDB with Panache uses the link:{mongodb-doc-root-url}/fundamentals/data-formats/document-data-format-pojo[PojoCodecProvider], a MongoDB codec which mandates the presence of a parameterless constructor. Therefore, if you want to use a data class as an entity class, you need a way to make Kotlin generate an empty constructor. To do so, you need to provide default values for all the fields of your classes. @@ -843,7 +846,7 @@ First, you can create a BSON Codec which will be automatically registered by Qua See this part of the documentation: xref:mongodb.adoc#simplifying-mongodb-client-usage-using-bson-codec[Using BSON codec]. Another option is to use the `@BsonCreator` annotation to tell the `PojoCodecProvider` to use the Kotlin data class default constructor, -in this case all constructor parameters have to be annotated with `@BsonProperty`: see link:{mongodb-doc-root-url}/bson/pojos/#supporting-pojos-without-no-args-constructors[Supporting pojos without no args constructor]. +in this case all constructor parameters have to be annotated with `@BsonProperty`: see link:{mongodb-doc-root-url}/fundamentals/data-formats/pojo-customization/#pojos-without-no-argument-constructors[Supporting pojos without no args constructor]. This will only work when the entity extends `PanacheMongoEntityBase` and not `PanacheMongoEntity`, as the ID field also needs to be included in the constructor. @@ -891,7 +894,7 @@ and when defining your repositories: `ReactivePanacheMongoRepository` or `Reacti [TIP] .Mutiny ==== -The reactive API of the MongoDB with Panache uses Mutiny reactive types. +The reactive API of MongoDB with Panache uses Mutiny reactive types. If you are not familiar with Mutiny, check xref:mutiny-primer.adoc[Mutiny - an intuitive reactive programming library]. ==== diff --git a/docs/src/main/asciidoc/mongodb.adoc b/docs/src/main/asciidoc/mongodb.adoc index 7831c5eb77cb6..9e8c9bbe564fb 100644 --- a/docs/src/main/asciidoc/mongodb.adoc +++ b/docs/src/main/asciidoc/mongodb.adoc @@ -240,9 +240,11 @@ Because the `mongo+srv` protocol often used to connect to MongoDB requires JNDI, === Dev Services (Configuration Free Databases) Quarkus supports a feature called Dev Services that allows you to create various datasources without any config. In the case of MongoDB this support extends to the default MongoDB connection. -What that means practically, is that if you have not configured `quarkus.mongodb.connection-string` Quarkus will automatically start a MongoDB container when running tests or dev mode, +What that means practically, is that if you have not configured `quarkus.mongodb.connection-string`, Quarkus will automatically start a MongoDB container when running tests or in dev mode, and automatically configure the connection. +MongoDB Dev Services is based on link:https://www.testcontainers.org/modules/databases/mongodb/[Testcontainers MongoDB module] that will start a single node replicaset. + When running the production version of the application, the MongoDB connection need to be configured as normal, so if you want to include a production database config in your `application.properties` and continue to use Dev Services we recommend that you use the `%prod.` profile to define your MongoDB settings. @@ -298,7 +300,7 @@ As by default, `MongoClient` is configured to access a local MongoDB database on If you want to use Docker to run a MongoDB database, you can use the following command to launch one: [source,bash] ---- -docker run -ti --rm -p 27017:27017 mongo:4.0 +docker run -ti --rm -p 27017:27017 mongo:4.4 ---- [NOTE] @@ -316,11 +318,13 @@ In the `src/main/resources/META-INF/resources` directory, add a `fruits.html` fi You can now interact with your REST service: :devtools-wrapped: + * start Quarkus with: + include::{includes}/devtools/dev.adoc[] * open a browser to `http://localhost:8080/fruits.html` * add new fruits to the list via the form + :!devtools-wrapped: [[reactive]] @@ -329,13 +333,6 @@ 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. -[NOTE] -.Deprecation -==== -The `io.quarkus.mongodb.ReactiveMongoClient` client is deprecated and will be removed in the future. -It is recommended to switch to the `io.quarkus.mongodb.reactive.ReactiveMongoClient` client providing the `Mutiny` API. -==== - [TIP] .Mutiny ==== @@ -430,7 +427,7 @@ By using a Bson `Codec`, the MongoDB Client will take care of the transformation 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://mongodb.github.io/mongo-java-driver/3.10/bson/codecs. +More information in the codec documentation: https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/data-formats/codecs/. [source,java] ---- @@ -577,7 +574,7 @@ public class CodecFruitService { == The POJO Codec -The link:https://mongodb.github.io/mongo-java-driver/3.12/bson/pojos/[POJO Codec] provides a set of annotations that enable the customization of +The link:https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/data-formats/document-data-format-pojo/[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 One of these annotations is the `@BsonDiscriminator` annotation that allows to storage multiple Java types in a single MongoDB collection by adding @@ -624,7 +621,10 @@ Read the xref:opentracing.adoc[OpenTracing] guide, for how to configure OpenTrac == Testing helpers -To start a MongoDB database for your unit tests, Quarkus provides two `QuarkusTestResourceLifecycleManager` that relies on link:https://github.com/flapdoodle-oss/de.flapdoodle.embed.mongo[Flapdoodle embedded MongoDB]. +xref:#dev-services[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 link:https://github.com/flapdoodle-oss/de.flapdoodle.embed.mongo[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.