From 87031389a03208ed56d53c4875e96ccec928c998 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 8 Aug 2024 10:53:00 -0400 Subject: [PATCH 1/5] DOCSP-41122: Choose a Connection Target --- source/connect.txt | 10 +- source/connect/connection-targets.txt | 119 ++++++++++++++++++ source/includes/connect/connection-targets.kt | 56 +++++++++ 3 files changed, 180 insertions(+), 5 deletions(-) create mode 100644 source/connect/connection-targets.txt create mode 100644 source/includes/connect/connection-targets.kt diff --git a/source/connect.txt b/source/connect.txt index e1a34974..946eac4e 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -19,13 +19,13 @@ Connect to MongoDB :keywords: client, ssl, tls, localhost .. toctree:: - :titlesonly: - :maxdepth: 1 + :titlesonly: + :maxdepth: 1 - /connect/stable-api -.. + /connect/stable-api + /connect/connection-targets + .. /connect/mongoclient -.. /connect/connection-targets .. /connect/connection-options .. /connect/tls .. /connect/network-compression diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt new file mode 100644 index 00000000..7d914af1 --- /dev/null +++ b/source/connect/connection-targets.txt @@ -0,0 +1,119 @@ +.. _kotlin-sync-connection-targets: + +========================== +Choose a Connection Target +========================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: connection string, URI, server, settings, client + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use a connection string and a ``MongoClient`` object +to connect to different types of MongoDB deployments. + +Atlas +----- + +To connect to a MongoDB deployment on Atlas, include the following elements +in your connection string: + +- The URL of your Atlas cluster +- Your MongoDB username +- Your MongoDB password + +Then, pass your connection string to the ``MongoClient`` constructor. + +.. tip:: + + Follow the :atlas:`Atlas driver connection guide ` + to retrieve your connection string. + +When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid +breaking changes when Atlas upgrades to a new version of {+mdb-server+}. +To learn more about the {+stable-api+} feature, see :ref:``. + +The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The +code also uses the ``serverApi()`` method to specify a {+stable-api+} version. + +.. literalinclude:: /includes/connect/connection-targets.kt + :language: kotlin + :start-after: start-connect + :end-before: end-connect + :dedent: + +Local Deployments +----------------- + +To connect to a local MongoDB deployment, use ``localhost`` as the hostname. By +default, the ``mongod`` process runs on port 27017, though you can customize this for +your deployment. + +The following code shows how to use the {+driver-short+} to connect to a local MongoDB +deployment: + +.. literalinclude:: /includes/connect/connection-targets.kt + :language: kotlin + :start-after: start-connect-local + :end-before: end-connect-local + :dedent: + +Replica Sets +------------ + +To connect to a replica set, specify the hostnames (or IP addresses) and +port numbers of the replica-set members. + +If you aren't able to provide a full list of hosts in the replica set, you can +specify one or more of the hosts in the replica set and instruct the {+driver-short+} to +perform automatic discovery to find the others. To instruct the driver to perform +automatic discovery, perform one of the following actions: + +- Specify the name of the replica set as the value of the ``replicaSet`` parameter. +- Specify ``false`` as the value of the ``directConnection`` parameter. +- Specify more than one host in the replica set. + +The following examples show how to specify multiple hosts to a ``MongoClient`` instance +using either the ``ConnectionString`` or ``MongoClientSettings`` class. Select the tab +that corresponds to your preferred class. + +.. tabs:: + + .. tab:: ConnectionString + :tabid: connectionstring + + .. literalinclude:: /includes/connect/connection-targets.kt + :language: kotlin + :start-after: start-connect-rs-connection-string + :end-before: end-connect-rs-connection-string + :dedent: + + .. tab:: MongoClientSettings + :tabid: connectionstring + + .. literalinclude:: /includes/connect/connection-targets.kt + :language: kotlin + :start-after: start-connect-rs-settings + :end-before: end-connect-rs-settings + :dedent: + +.. note:: + + The ``MongoClient`` constructor is *non-blocking*. + When you connect to a replica set, the constructor returns immediately while the + client uses background threads to connect to the replica set. + + If you construct a ``MongoClient`` and immediately print the string representation + of its ``nodes`` attribute, the list might be empty while the client connects to + the replica-set members. diff --git a/source/includes/connect/connection-targets.kt b/source/includes/connect/connection-targets.kt new file mode 100644 index 00000000..1c44df13 --- /dev/null +++ b/source/includes/connect/connection-targets.kt @@ -0,0 +1,56 @@ +package org.example +import com.mongodb.ConnectionString +import com.mongodb.MongoClientSettings +import com.mongodb.ServerAddress +import com.mongodb.ServerApi +import com.mongodb.ServerApiVersion +import com.mongodb.kotlin.client.MongoClient + +fun main() { + // start-connect + val connectionString = ConnectionString("") + + val serverApi = ServerApi.builder() + .version(ServerApiVersion.V1) + .build() + + val settings = MongoClientSettings.builder() + .applyConnectionString(connectionString) + .serverApi(serverApi) + .build() + + val mongoClient = MongoClient.create(settings) + // end-connect + + // start-connect-local + val connectionString = ConnectionString("mongodb://localhost:27017") + + val settings = MongoClientSettings.builder() + .applyConnectionString(connectionString) + .build() + + val mongoClient = MongoClient.create(settings) + // end-connect-local + + // start-connect-rs-connection-string + val connectionString = ConnectionString("mongodb://host1:27017,host2:27017,host3:27017/") + val mongoClient = MongoClient.create(connectionString) + // end-connect-rs-connection-string + + // start-connect-rs-settings + val hosts = listOf( + ServerAddress("host1", 27017), + ServerAddress("host2", 27017), + ServerAddress("host3", 27017) + ) + + val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder -> + builder.hosts(hosts) + } + .build() + + val mongoClient = MongoClient.create(settings) + // end-connect-rs-settings +} + From 8f4a665f9cb783508217a2ffb7e42e9fd4d915f0 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 8 Aug 2024 11:00:11 -0400 Subject: [PATCH 2/5] Fixes --- source/connect/connection-targets.txt | 2 +- source/includes/connect/connection-targets.kt | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index 7d914af1..44ea37a1 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -100,7 +100,7 @@ that corresponds to your preferred class. :dedent: .. tab:: MongoClientSettings - :tabid: connectionstring + :tabid: mongoclientsettings .. literalinclude:: /includes/connect/connection-targets.kt :language: kotlin diff --git a/source/includes/connect/connection-targets.kt b/source/includes/connect/connection-targets.kt index 1c44df13..26721747 100644 --- a/source/includes/connect/connection-targets.kt +++ b/source/includes/connect/connection-targets.kt @@ -10,10 +10,12 @@ fun main() { // start-connect val connectionString = ConnectionString("") + // Defines Stable API version val serverApi = ServerApi.builder() .version(ServerApiVersion.V1) .build() + // Uses MongoClientSettings to apply connection string and specify the Stable API version val settings = MongoClientSettings.builder() .applyConnectionString(connectionString) .serverApi(serverApi) From 328671caf3e59cf8491fd76f8d40af42669e7283 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 8 Aug 2024 13:54:25 -0400 Subject: [PATCH 3/5] Address AS feedback --- source/connect/connection-targets.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index 44ea37a1..ea8deef4 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -42,7 +42,8 @@ Then, pass your connection string to the ``MongoClient`` constructor. When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid breaking changes when Atlas upgrades to a new version of {+mdb-server+}. -To learn more about the {+stable-api+} feature, see :ref:``. +To learn more about the {+stable-api+} feature, see the :ref:`` +guide. The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The code also uses the ``serverApi()`` method to specify a {+stable-api+} version. @@ -84,9 +85,9 @@ automatic discovery, perform one of the following actions: - Specify ``false`` as the value of the ``directConnection`` parameter. - Specify more than one host in the replica set. -The following examples show how to specify multiple hosts to a ``MongoClient`` instance -using either the ``ConnectionString`` or ``MongoClientSettings`` class. Select the tab -that corresponds to your preferred class. +The following examples show how to connect to a MongoDB replica set running on port +``27017`` of three different hosts by using either the ``ConnectionString`` or +``MongoClientSettings`` class. Select the tab that corresponds to your preferred class. .. tabs:: From d8744fd3742b30ca9adc8dff023fa40c41a2c063 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Fri, 9 Aug 2024 14:15:54 -0400 Subject: [PATCH 4/5] Address technical feedback --- source/includes/connect/connection-targets.kt | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/source/includes/connect/connection-targets.kt b/source/includes/connect/connection-targets.kt index 26721747..c9080d9e 100644 --- a/source/includes/connect/connection-targets.kt +++ b/source/includes/connect/connection-targets.kt @@ -8,8 +8,6 @@ import com.mongodb.kotlin.client.MongoClient fun main() { // start-connect - val connectionString = ConnectionString("") - // Defines Stable API version val serverApi = ServerApi.builder() .version(ServerApiVersion.V1) @@ -17,7 +15,7 @@ fun main() { // Uses MongoClientSettings to apply connection string and specify the Stable API version val settings = MongoClientSettings.builder() - .applyConnectionString(connectionString) + .applyConnectionString("") .serverApi(serverApi) .build() @@ -25,18 +23,15 @@ fun main() { // end-connect // start-connect-local - val connectionString = ConnectionString("mongodb://localhost:27017") - val settings = MongoClientSettings.builder() - .applyConnectionString(connectionString) + .applyConnectionString("mongodb://localhost:27017") .build() val mongoClient = MongoClient.create(settings) // end-connect-local // start-connect-rs-connection-string - val connectionString = ConnectionString("mongodb://host1:27017,host2:27017,host3:27017/") - val mongoClient = MongoClient.create(connectionString) + val mongoClient = MongoClient.create("mongodb://host1:27017,host2:27017,host3:27017/") // end-connect-rs-connection-string // start-connect-rs-settings From 5eb0529bcf4f5ac4afd6b213f3dc3a29170a4362 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 13 Aug 2024 09:23:52 -0400 Subject: [PATCH 5/5] Fix link --- source/connect/connection-targets.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index ea8deef4..625e85a2 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -37,7 +37,7 @@ Then, pass your connection string to the ``MongoClient`` constructor. .. tip:: - Follow the :atlas:`Atlas driver connection guide ` + Follow the :atlas:`Atlas driver connection guide ` to retrieve your connection string. When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid