From bd33ef7f62cd5b284de9e07a599c96b5f9afc7c4 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 23 Jul 2024 09:37:19 -0400 Subject: [PATCH] DOCSP-41120: connection landing (#12) * DOCSP-41120: connection landing * Draft * staging * fix error * add intro sentences * MM PR fixes 2 --- snooty.toml | 1 + source/connect.txt | 190 ++++++++++++++++++ source/includes/connect/compression-tabs.rst | 27 +++ .../disable-host-verification-tabs.rst | 24 +++ source/includes/connect/tls-tabs.rst | 24 +++ source/includes/connect/zlib-level-tabs.rst | 26 +++ .../usage-examples/connect-sample-app.kt | 15 ++ source/index.txt | 7 + 8 files changed, 314 insertions(+) create mode 100644 source/connect.txt create mode 100644 source/includes/connect/compression-tabs.rst create mode 100644 source/includes/connect/disable-host-verification-tabs.rst create mode 100644 source/includes/connect/tls-tabs.rst create mode 100644 source/includes/connect/zlib-level-tabs.rst create mode 100644 source/includes/usage-examples/connect-sample-app.kt diff --git a/snooty.toml b/snooty.toml index 7f974e8..dbce4a8 100644 --- a/snooty.toml +++ b/snooty.toml @@ -8,6 +8,7 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv", toc_landing_pages = [ "/read", + "/connect", "/indexes", "work-with-indexes", ] diff --git a/source/connect.txt b/source/connect.txt new file mode 100644 index 0000000..63f450d --- /dev/null +++ b/source/connect.txt @@ -0,0 +1,190 @@ +.. _kotlin-sync-connect: + +================== +Connect to MongoDB +================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to use the Kotlin Sync driver to connect to MongoDB. + :keywords: client, ssl, tls, localhost + +.. .. toctree:: +.. :titlesonly: +.. :maxdepth: 1 +.. +.. /connect/mongoclient +.. /connect/connection-targets +.. /connect/connection-options +.. /connect/tls +.. /connect/network-compression +.. /connect/server-selection +.. /connect/stable-api +.. /connect/csot + +Overview +-------- + +This page contains code examples that show how to use the +{+driver-short+} to connect your application to MongoDB by specifying +various settings. + +.. .. tip:: +.. +.. To learn more about the connection options on this page, see the link +.. provided in each section. + +To use a connection example from this page, copy the code example into the +:ref:`sample application ` or your own application. +Be sure to replace all placeholders in the code examples, such as +````, with the relevant values for your MongoDB deployment. + +.. _kotlin-sync-connect-sample: + +.. include:: /includes/usage-examples/sample-app-intro.rst + +.. literalinclude:: /includes/usage-examples/connect-sample-app.kt + :language: python + :copyable: true + :linenos: + :emphasize-lines: 6-8 + +Connection +---------- + +The following sections describe how to connect to different targets, +such as a local instance of MongoDB or a cloud-hosted instance on Atlas. + +Local Deployment +~~~~~~~~~~~~~~~~ + +The following code shows the connection string to connect to a local +instance of MongoDB: + +.. code-block:: kotlin + + val uri = "mongodb://localhost:27017/" + val mongoClient = MongoClient.create(uri) + +Atlas +~~~~~ + +The following code shows the connection string to connect to a +deployment hosted on Atlas: + +.. code-block:: kotlin + + val uri = "mongodb+srv://:@/?" + val mongoClient = MongoClient.create(uri) + +Replica Set +~~~~~~~~~~~ + +The following code shows the connection string to connect to a +replica set: + +.. code-block:: kotlin + + val uri = "mongodb://:/?replicaSet=" + val mongoClient = MongoClient.create(uri) + +Transport Layer Security (TLS) +------------------------------ + +The following sections describe how to connect to MongoDB +while enabling the TLS protocol. + +Enable TLS +~~~~~~~~~~ + +The following tabs demonstrate how to enable TLS on a connection: + +.. include:: /includes/connect/tls-tabs.rst + +.. To learn more about enabling TLS, see :ref:`kotlin-sync-enable-tls` in +.. the TLS configuration guide. + +Disable Hostname Verification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following tabs demonstrate how to disable hostname verification when +connecting by using TLS: + +.. include:: /includes/connect/disable-host-verification-tabs.rst + +.. To learn more about disabling hostname verification, see :ref:`kotlin-sync-insecure-tls` in +.. the TLS configuration guide. + +Network Compression +------------------- + +The following sections describe how to connect to MongoDB +while specifying network compression algorithms. + +Compression Algorithms +~~~~~~~~~~~~~~~~~~~~~~ + +The following tabs demonstrate how to specify all available compressors +while connecting to MongoDB: + +.. include:: /includes/connect/compression-tabs.rst + +.. To learn more about specifying compression algorithms, see +.. :ref:`kotlin-sync-enable-compression` in the Network Compression guide. + +zlib Compression Level +~~~~~~~~~~~~~~~~~~~~~~ + +The following tabs demonstrate how to specify a compression level for +the ``zlib`` compressor: + +.. include:: /includes/connect/zlib-level-tabs.rst + +.. To learn more about setting the zlib compression level, see +.. :ref:`kotlin-sync-enable-compression` in the Network Compression guide. + +Server Selection +---------------- + +The following code shows a connection string that specifies a server +selection function: + +.. code-block:: kotlin + + val client = MongoClient.create("mongodb://:@:", + server_selector=) + +.. To learn more about customizing server selection, see +.. :ref:`kotlin-sync-server-selection`. + +{+stable-api+} +-------------- + +The following code shows how to specify Stable API settings within a +``MongoClientSettings`` instance: + +.. code-block:: kotlin + + val serverApi = ServerApi.builder() + .version(ServerApiVersion.V1) + .build() + + val uri = "" + + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString(uri)) + .serverApi(serverApi) + .build() + + val client = MongoClient.create(settings) + +.. To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`. diff --git a/source/includes/connect/compression-tabs.rst b/source/includes/connect/compression-tabs.rst new file mode 100644 index 0000000..d039503 --- /dev/null +++ b/source/includes/connect/compression-tabs.rst @@ -0,0 +1,27 @@ +.. tabs:: + + .. tab:: MongoClient + :tabid: mongoclient + + .. code-block:: kotlin + + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString("")) + .compressorList( + listOf( + MongoCompressor.createSnappyCompressor(), + MongoCompressor.createZlibCompressor(), + MongoCompressor.createZstdCompressor()) + ) + .build() + + val mongoClient = MongoClient.create(settings) + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: kotlin + + val uri = ConnectionString("mongodb+srv://:@/?compressors=snappy,zlib,zstd") + + val mongoClient = MongoClient.create(uri) diff --git a/source/includes/connect/disable-host-verification-tabs.rst b/source/includes/connect/disable-host-verification-tabs.rst new file mode 100644 index 0000000..8acb68c --- /dev/null +++ b/source/includes/connect/disable-host-verification-tabs.rst @@ -0,0 +1,24 @@ +.. tabs:: + + .. tab:: MongoClient + :tabid: mongoclient + + .. code-block:: kotlin + + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString("")) + .applyToSslSettings { builder -> + builder.enabled(true) + builder.invalidHostNameAllowed(true) + } + .build() + val mongoClient = MongoClient.create(settings); + + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: kotlin + + val uri = "mongodb://:@:/?"tls=true&tlsAllowInvalidHostnames=true" + val mongoClient = MongoClient.create(uri) \ No newline at end of file diff --git a/source/includes/connect/tls-tabs.rst b/source/includes/connect/tls-tabs.rst new file mode 100644 index 0000000..40c0c2a --- /dev/null +++ b/source/includes/connect/tls-tabs.rst @@ -0,0 +1,24 @@ +.. tabs:: + + .. tab:: MongoClient + :tabid: mongoclient + + .. code-block:: kotlin + + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString("")) + .applyToSslSettings { builder -> + builder.enabled(true) + } + .build() + + val mongoClient = MongoClient.create(settings) + + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: kotlin + + val uri = "mongodb+srv://:@?tls=true" + val mongoClient = MongoClient.create(uri) \ No newline at end of file diff --git a/source/includes/connect/zlib-level-tabs.rst b/source/includes/connect/zlib-level-tabs.rst new file mode 100644 index 0000000..0d85448 --- /dev/null +++ b/source/includes/connect/zlib-level-tabs.rst @@ -0,0 +1,26 @@ +.. tabs:: + + .. tab:: MongoClient + :tabid: mongoclient + + .. code-block:: kotlin + + val zlib = MongoCompressor.createZlibCompressor() + + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString(uri)) + .compressorList(listOf(zlib.withProperty(MongoCompressor.LEVEL, ))) + .build() + + val mongoClient = MongoClient.create(settings) + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: kotlin + + val uri = "mongodb://:@:/?" + + "compressors=zlib" + + "zlibCompressionLevel=" + + val mongoClient = MongoClient.create(uri) \ No newline at end of file diff --git a/source/includes/usage-examples/connect-sample-app.kt b/source/includes/usage-examples/connect-sample-app.kt new file mode 100644 index 0000000..1bd7586 --- /dev/null +++ b/source/includes/usage-examples/connect-sample-app.kt @@ -0,0 +1,15 @@ +import com.mongodb.kotlin.client.MongoClient +import org.bson.Document + +fun main() { + + // Start example code here + + // End example code here + + val database = mongoClient.getDatabase("admin") + + val command = Document("ping", 1) + val commandResult = database.runCommand(command) + println("Pinged your deployment. You successfully connected to MongoDB!") +} \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index bbcfc4b..c89afcb 100644 --- a/source/index.txt +++ b/source/index.txt @@ -13,6 +13,7 @@ .. toctree:: + /connect /write-operations /read /indexes @@ -47,6 +48,12 @@ Quick Start Learn how to establish a connection to MongoDB Atlas and begin working with data in the :ref:`Quick Start ` section. +Connect to MongoDB +------------------ + +Learn how to create and configure a connection to a MongoDB deployment +in the :ref:`kotlin-sync-connect` section. + What's New ----------