DOCSP-41121 Connect to Mongo Client

source/connect.txt

@@ -22,11 +22,11 @@ Connect to MongoDB
    :titlesonly:
    :maxdepth: 1
 
-   /connect/stable-api
+   /connect/mongoclient
    /connect/connection-targets
+   /connect/connection-options
+   /connect/stable-api
 
-..    /connect/mongoclient
-..    /connect/connection-options
 ..    /connect/tls
 ..    /connect/network-compression
 ..    /connect/server-selection

source/connect/connection-options.txt

@@ -0,0 +1,21 @@
+.. _kotlin-sync-connection-options:
+
+==========================
+Specify Connection Options
+==========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: connection string, URI, server, Atlas, settings, configure
+
+Overview
+--------

source/connect/mongoclient.txt

@@ -0,0 +1,131 @@
+.. _kotlin-sync-mongoclient:
+
+====================
+Create a MongoClient
+====================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: connection string, URI, server, Atlas, settings, client
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+To connect to a MongoDB deployment, you need two things:
+
+- A **connection URI**, also known as a *connection string*, which tells the {+driver-short+}
+  which MongoDB deployment to connect to.
+- A **MongoClient** object, which creates the connection to and performs 
+  operations on the MongoDB deployment.
+
+You can also use ``MongoClientSettings`` to customize the way the {+driver-short+} behaves
+while connected to MongoDB.
+
+This guide shows you how to create a connection string and use a ``MongoClient`` object
+to connect to MongoDB.
+
+.. _kotlin-sync-connection-uri:
+
+Connection URI
+--------------
+
+A standard connection string includes the following components:
+
+.. TODO, add this as last sentence for ``username:password`` description once a kotlin auth page is made: 
+.. For more information about the ``authSource`` connection option, see :ref:`kotlin-sync-auth`. 
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Component
+     - Description
+
+   * - ``mongodb://``
+
+     - Required. A prefix that identifies this as a string in the
+       standard connection format.
+
+   * - ``username:password``
+
+     - Optional. Authentication credentials. If you include these, the client
+       authenticates the user against the database specified in ``authSource``.
+
+   * - ``host[:port]``
+
+     - Required. The host and optional port number where MongoDB is running. If you don't
+       include the port number, the driver uses the default port, ``27017``.
+
+   * - ``/defaultauthdb``
+
+     - Optional. The authentication database to use if the
+       connection string includes ``username:password@``
+       authentication credentials but not the ``authSource`` option. If you don't include 
+       this component, the client authenticates the user against the ``admin`` database.
+
+   * - ``?<options>``
+
+     - Optional. A query string that specifies connection-specific
+       options as ``<name>=<value>`` pairs. See
+       :ref:`kotlin-sync-connection-options` for a full description of
+       these options.
+
+For more information about creating a connection string, see
+:manual:`Connection Strings </reference/connection-string>` in the
+MongoDB Server documentation.
+
+Atlas Connection Example
+------------------------
+
+To connect to a MongoDB deployment on Atlas, you must first create a client. 
+
+You can pass a connection URI as a string to the ``MongoClient.create()`` method 
+to connect to a MongoDB instance:
+
+.. literalinclude:: /includes/connect/mongoclient2.kt
+   :start-after: start-connect-to-atlas-w-uri
+   :end-before: end-connect-to-atlas-w-uri
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+You can also create a client with your desired configurations by passing a 
+``MongoClientSettings`` object to the ``MongoClient.create()`` method.
+
+To instantiate a ``MongoClientSettings`` object, use the builder method to 
+specify your connection string, using the ``applyConnectionString()`` method, 
+and any other client options. Once you have your desired configuration, 
+call the ``build()`` method.
+
+You can set the Stable API version client option to avoid breaking changes when 
+you upgrade to a new server version. To learn more about the Stable API feature, 
+see the :ref:`Stable API page <kotlin-sync-stable-api>`. 
+
+The following code shows how you can specify the connection string and the 
+Stable API client option when connecting to a MongoDB deployment on Atlas 
+and verify that the connection is successful:
+
+.. literalinclude:: /includes/connect/mongoclient.kt
+   :start-after: start-connect-to-atlas
+   :end-before: end-connect-to-atlas
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+API Documentation
+-----------------
+
+For more information about creating a ``MongoClient`` object with the 
+{+driver-short+}, see the following API documentation: 
+
+- `MongoClient <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__
+- `MongoClientSettings <{+core-api+}com/mongodb/MongoClientSettings.html>`__

source/includes/connect/mongoclient.kt

@@ -0,0 +1,37 @@
+import com.mongodb.*
+import com.mongodb.kotlin.client.MongoClient
+import org.bson.BsonInt64
+import org.bson.Document
+
+fun main() {
+
+    // start-connect-to-atlas
+    // start-connect-to-atlas-w-uri
+    // Replace the placeholder with your Atlas connection string
+    val uri = "<connection string>"
+    val mongoClient1 = MongoClient.create(uri)
+    // end-connect-to-atlas-w-uri
+
+    // Construct a ServerApi instance using the ServerApi.builder() method
+    val serverApi = ServerApi.builder()
+        .version(ServerApiVersion.V1)
+        .build()
+    val settings = MongoClientSettings.builder()
+        .applyConnectionString(ConnectionString(uri))
+        .serverApi(serverApi)
+        .build()
+
+    // Create a new client and connect to the server
+    val mongoClient = MongoClient.create(settings)
+    val database = mongoClient.getDatabase("sample_mflix")
+
+    try {
+        // Send a ping to confirm a successful connection
+        val command = Document("ping", BsonInt64(1))
+        val commandResult = database.runCommand(command)
+        println("Pinged your deployment. You successfully connected to MongoDB!")
+    } catch (me: MongoException) {
+        System.err.println(me)
+    }
+    // end-connect-to-atlas
+}

source/includes/connect/mongoclient2.kt

@@ -0,0 +1,23 @@
+import com.mongodb.*
+import com.mongodb.kotlin.client.MongoClient
+
+fun main() {
+
+    // start-connect-to-atlas-w-uri
+    // Replace the placeholder with your Atlas connection string
+    val uri = "<connection string>"
+
+    // Create a new client and connect to the server
+    val mongoClient = MongoClient.create(uri)
+    val database = mongoClient.getDatabase("sample_mflix")
+    // end-connect-to-atlas-w-uri
+
+    try {
+        // Send a ping to confirm a successful connection
+        val command = Document("ping", BsonInt64(1))
+        val commandResult = database.runCommand(command)
+        println("Pinged your deployment. You successfully connected to MongoDB!")
+    } catch (me: MongoException) {
+        System.err.println(me)
+    }
+}