From 9091f90b694cec0c95481b465c35b696515a7901 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 16 Jul 2024 16:17:32 -0400 Subject: [PATCH 1/6] DOCSP-41120: connection landing --- snooty.toml | 3 +- source/connect.txt | 201 ++++++++++++++++++ source/includes/connect/ca-file-tabs.rst | 14 ++ source/includes/connect/insecure-tls-tabs.rst | 0 source/includes/connect/tls-tabs.rst | 24 +++ .../usage-examples/connect-sample-app.kt | 15 ++ source/index.txt | 7 + 7 files changed, 263 insertions(+), 1 deletion(-) create mode 100644 source/connect.txt create mode 100644 source/includes/connect/ca-file-tabs.rst create mode 100644 source/includes/connect/insecure-tls-tabs.rst create mode 100644 source/includes/connect/tls-tabs.rst create mode 100644 source/includes/usage-examples/connect-sample-app.kt diff --git a/snooty.toml b/snooty.toml index a9043f1..c6139d7 100644 --- a/snooty.toml +++ b/snooty.toml @@ -7,7 +7,8 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv", ] toc_landing_pages = [ - "/read" + "/read", + "/connect" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/connect.txt b/source/connect.txt new file mode 100644 index 0000000..4ea094c --- /dev/null +++ b/source/connect.txt @@ -0,0 +1,201 @@ +.. _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 +~~~~~ + +.. code-block:: kotlin + + val uri = "" + + val serverApi = ServerApi.builder() + .version(ServerApiVersion.V1) + .build() + + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString(uri)) + .serverApi(serverApi) + .build() + + val mongoClient = MongoClient.create(settings) + +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 +~~~~~~~~~~ + +.. include:: /includes/connect/tls-tabs.rst + +.. To learn more about enabling TLS, see :ref:`kotlin-sync-enable-tls` in +.. the TLS configuration guide. + +Allow Insecure TLS +~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/connect/insecure-tls-tabs.rst + +.. To learn more about allowing insecure TLS, see :ref:`kotlin-sync-insecure-tls` in +.. the TLS configuration guide. + +Disable Certificate Validation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/connect/disable-cert-validation-tabs.rst + +To learn more about disabling certificate validation, see :ref:`kotlin-sync-insecure-tls` in +the TLS configuration guide. + +Disable Hostname Verification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. 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 +------------------- + +Compression Algorithms +~~~~~~~~~~~~~~~~~~~~~~ + +.. 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 +~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. tab:: MongoClient + :tabid: mongoclient + + .. code-block:: kotlin + + client = pymongo.MongoClient("mongodb://:@:", + compressors = "zlib", + zlibCompressionLevel=) + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: kotlin + + uri = ("mongodb://:@:/?" + "compressors=zlib" + "zlibCompressionLevel=") + client = pymongo.MongoClient(uri) + +To learn more about setting the zlib compression level, see +:ref:`kotlin-sync-enable-compression` in the Network Compression guide. + +Server Selection +---------------- + +.. code-block:: kotlin + + client = pymongo.MongoClient("mongodb://:@:", + server_selector=) + +To learn more about customizing server selection, see +:ref:`kotlin-sync-server-selection`. + +{+stable-api+} +-------------- + +.. code-block:: kotlin + + from pymongo.server_api import ServerApi + + client = pymongo.MongoClient("mongodb://:@", + server_api=ServerApi("<{+stable-api+} version>")) + +To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`. diff --git a/source/includes/connect/ca-file-tabs.rst b/source/includes/connect/ca-file-tabs.rst new file mode 100644 index 0000000..a0e8c84 --- /dev/null +++ b/source/includes/connect/ca-file-tabs.rst @@ -0,0 +1,14 @@ +.. tabs:: + + .. tab:: MongoClient + :tabid: mongoclient + + .. code-block:: kotlin + + + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: kotlin + diff --git a/source/includes/connect/insecure-tls-tabs.rst b/source/includes/connect/insecure-tls-tabs.rst new file mode 100644 index 0000000..e69de29 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/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 f31870b..aedca69 100644 --- a/source/index.txt +++ b/source/index.txt @@ -13,6 +13,7 @@ .. toctree:: + /connect /read /faq /connection-troubleshooting @@ -45,6 +46,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 ---------- From a113144646b5ed04b8be266958b67eeeb3d8c580 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 17 Jul 2024 11:48:58 -0400 Subject: [PATCH 2/6] Draft --- source/connect.txt | 71 +++++++++---------- source/includes/connect/ca-file-tabs.rst | 14 ---- source/includes/connect/compression-tabs.rst | 27 +++++++ .../disable-host-verification-tabs.rst | 24 +++++++ source/includes/connect/insecure-tls-tabs.rst | 0 5 files changed, 86 insertions(+), 50 deletions(-) delete mode 100644 source/includes/connect/ca-file-tabs.rst create mode 100644 source/includes/connect/compression-tabs.rst create mode 100644 source/includes/connect/disable-host-verification-tabs.rst delete mode 100644 source/includes/connect/insecure-tls-tabs.rst diff --git a/source/connect.txt b/source/connect.txt index 4ea094c..013232f 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -115,29 +115,13 @@ Enable TLS .. To learn more about enabling TLS, see :ref:`kotlin-sync-enable-tls` in .. the TLS configuration guide. -Allow Insecure TLS -~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/connect/insecure-tls-tabs.rst - -.. To learn more about allowing insecure TLS, see :ref:`kotlin-sync-insecure-tls` in -.. the TLS configuration guide. - -Disable Certificate Validation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/connect/disable-cert-validation-tabs.rst - -To learn more about disabling certificate validation, see :ref:`kotlin-sync-insecure-tls` in -the TLS configuration guide. - Disable Hostname Verification ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. 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. +.. To learn more about disabling hostname verification, see :ref:`kotlin-sync-insecure-tls` in +.. the TLS configuration guide. Network Compression ------------------- @@ -147,8 +131,8 @@ Compression Algorithms .. include:: /includes/connect/compression-tabs.rst -To learn more about specifying compression algorithms, see -:ref:`kotlin-sync-enable-compression` in the Network Compression guide. +.. To learn more about specifying compression algorithms, see +.. :ref:`kotlin-sync-enable-compression` in the Network Compression guide. zlib Compression Level ~~~~~~~~~~~~~~~~~~~~~~ @@ -160,42 +144,57 @@ zlib Compression Level .. code-block:: kotlin - client = pymongo.MongoClient("mongodb://:@:", - compressors = "zlib", - zlibCompressionLevel=) + 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 - uri = ("mongodb://:@:/?" - "compressors=zlib" - "zlibCompressionLevel=") - client = pymongo.MongoClient(uri) + val uri = "mongodb://:@:/?" + + "compressors=zlib" + + "zlibCompressionLevel=" + + val mongoClient = MongoClient.create(uri) -To learn more about setting the zlib compression level, see -:ref:`kotlin-sync-enable-compression` in the Network Compression guide. +.. To learn more about setting the zlib compression level, see +.. :ref:`kotlin-sync-enable-compression` in the Network Compression guide. Server Selection ---------------- .. code-block:: kotlin - client = pymongo.MongoClient("mongodb://:@:", + val client = MongoClient.create("mongodb://:@:", server_selector=) -To learn more about customizing server selection, see -:ref:`kotlin-sync-server-selection`. +.. To learn more about customizing server selection, see +.. :ref:`kotlin-sync-server-selection`. {+stable-api+} -------------- .. code-block:: kotlin - from pymongo.server_api import ServerApi + 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) - client = pymongo.MongoClient("mongodb://:@", - server_api=ServerApi("<{+stable-api+} version>")) -To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`. +.. To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`. diff --git a/source/includes/connect/ca-file-tabs.rst b/source/includes/connect/ca-file-tabs.rst deleted file mode 100644 index a0e8c84..0000000 --- a/source/includes/connect/ca-file-tabs.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. tabs:: - - .. tab:: MongoClient - :tabid: mongoclient - - .. code-block:: kotlin - - - - .. tab:: Connection String - :tabid: connectionstring - - .. code-block:: kotlin - 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/insecure-tls-tabs.rst b/source/includes/connect/insecure-tls-tabs.rst deleted file mode 100644 index e69de29..0000000 From 4b56d24d2308fb6bb086c3311597106cbe70277c Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 17 Jul 2024 12:05:30 -0400 Subject: [PATCH 3/6] staging From b4727a53d9b5708709582250aa9caa43e745fb9c Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 17 Jul 2024 12:12:15 -0400 Subject: [PATCH 4/6] fix error --- source/validate-signatures.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/validate-signatures.txt b/source/validate-signatures.txt index c59c831..262d9e5 100644 --- a/source/validate-signatures.txt +++ b/source/validate-signatures.txt @@ -1,3 +1,3 @@ .. _kotlin-sync-validate-signatures: -.. sharedinclude:: dbx/jvm-validate-artifacts.rst +.. sharedinclude:: dbx/jvm/validate-artifacts.rst From 110ae03e2c6ca1482a99808688c8405c534f395e Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 17 Jul 2024 13:04:24 -0400 Subject: [PATCH 5/6] add intro sentences --- source/connect.txt | 66 +++++++++------------ source/includes/connect/zlib-level-tabs.rst | 26 ++++++++ 2 files changed, 54 insertions(+), 38 deletions(-) create mode 100644 source/includes/connect/zlib-level-tabs.rst diff --git a/source/connect.txt b/source/connect.txt index 013232f..15f8174 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -78,24 +78,20 @@ instance of MongoDB: Atlas ~~~~~ -.. code-block:: kotlin +The following code shows the connection string to connect to a +deployment hosted on Atlas. - val uri = "" - - val serverApi = ServerApi.builder() - .version(ServerApiVersion.V1) - .build() - - val settings = MongoClientSettings.builder() - .applyConnectionString(ConnectionString(uri)) - .serverApi(serverApi) - .build() +.. code-block:: kotlin - val mongoClient = MongoClient.create(settings) + 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=" @@ -110,6 +106,8 @@ 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 @@ -118,6 +116,9 @@ Enable TLS 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 @@ -126,9 +127,15 @@ Disable Hostname Verification 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 @@ -137,32 +144,10 @@ Compression Algorithms zlib Compression Level ~~~~~~~~~~~~~~~~~~~~~~ -.. tabs:: - - .. tab:: MongoClient - :tabid: mongoclient - - .. code-block:: kotlin - - val zlib = MongoCompressor.createZlibCompressor() +The following tabs demonstrate how to specify a compression level for +the ``zlib`` compressor: - 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) +.. 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. @@ -170,6 +155,9 @@ zlib Compression Level Server Selection ---------------- +The following code shows a connection string that specifies a server +selection function: + .. code-block:: kotlin val client = MongoClient.create("mongodb://:@:", @@ -181,6 +169,9 @@ 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() @@ -196,5 +187,4 @@ Server Selection val client = MongoClient.create(settings) - .. To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`. 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 From 5e443d0c42afada2ce1e93b5d94e02135bf6f075 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 17 Jul 2024 13:14:31 -0400 Subject: [PATCH 6/6] MM PR fixes 2 --- source/connect.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 15f8174..63f450d 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -79,7 +79,7 @@ Atlas ~~~~~ The following code shows the connection string to connect to a -deployment hosted on Atlas. +deployment hosted on Atlas: .. code-block:: kotlin @@ -90,7 +90,7 @@ Replica Set ~~~~~~~~~~~ The following code shows the connection string to connect to a -replica set. +replica set: .. code-block:: kotlin