DOCSP-41122: Choose a Connection Target

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

source/connect/connection-targets.txt

@@ -0,0 +1,120 @@
+.. _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 </driver-connection?tck=docs_driver_python>`
+   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 the :ref:`<kotlin-sync-stable-api>`
+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.
+
+.. 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 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::
+
+   .. 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: mongoclientsettings
+
+      .. 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.

source/includes/connect/connection-targets.kt

@@ -0,0 +1,53 @@
+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
+    // 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("<connection string URI>")
+        .serverApi(serverApi)
+        .build()
+
+    val mongoClient = MongoClient.create(settings)
+    // end-connect
+
+    // start-connect-local
+    val settings = MongoClientSettings.builder()
+        .applyConnectionString("mongodb://localhost:27017")
+        .build()
+
+    val mongoClient = MongoClient.create(settings)
+    // end-connect-local
+
+    // start-connect-rs-connection-string
+    val mongoClient = MongoClient.create("mongodb://host1:27017,host2:27017,host3:27017/")
+    // 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
+}
+