Skip to content

Commit bd33ef7

Browse files
rustagirrustagir
authored
DOCSP-41120: connection landing (#12)
* DOCSP-41120: connection landing * Draft * staging * fix error * add intro sentences * MM PR fixes 2
1 parent fe190a5 commit bd33ef7

File tree

8 files changed

+314
-0
lines changed

8 files changed

+314
-0
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
88

99
toc_landing_pages = [
1010
"/read",
11+
"/connect",
1112
"/indexes",
1213
"work-with-indexes",
1314
]

‎source/connect.txt

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
.. _kotlin-sync-connect:
2+
3+
==================
4+
Connect to MongoDB
5+
==================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:description: Learn how to use the Kotlin Sync driver to connect to MongoDB.
19+
:keywords: client, ssl, tls, localhost
20+
21+
.. .. toctree::
22+
.. :titlesonly:
23+
.. :maxdepth: 1
24+
..
25+
.. /connect/mongoclient
26+
.. /connect/connection-targets
27+
.. /connect/connection-options
28+
.. /connect/tls
29+
.. /connect/network-compression
30+
.. /connect/server-selection
31+
.. /connect/stable-api
32+
.. /connect/csot
33+
34+
Overview
35+
--------
36+
37+
This page contains code examples that show how to use the
38+
{+driver-short+} to connect your application to MongoDB by specifying
39+
various settings.
40+
41+
.. .. tip::
42+
..
43+
.. To learn more about the connection options on this page, see the link
44+
.. provided in each section.
45+
46+
To use a connection example from this page, copy the code example into the
47+
:ref:`sample application <kotlin-sync-connect-sample>` or your own application.
48+
Be sure to replace all placeholders in the code examples, such as
49+
``<hostname>``, with the relevant values for your MongoDB deployment.
50+
51+
.. _kotlin-sync-connect-sample:
52+
53+
.. include:: /includes/usage-examples/sample-app-intro.rst
54+
55+
.. literalinclude:: /includes/usage-examples/connect-sample-app.kt
56+
:language: python
57+
:copyable: true
58+
:linenos:
59+
:emphasize-lines: 6-8
60+
61+
Connection
62+
----------
63+
64+
The following sections describe how to connect to different targets,
65+
such as a local instance of MongoDB or a cloud-hosted instance on Atlas.
66+
67+
Local Deployment
68+
~~~~~~~~~~~~~~~~
69+
70+
The following code shows the connection string to connect to a local
71+
instance of MongoDB:
72+
73+
.. code-block:: kotlin
74+
75+
val uri = "mongodb://localhost:27017/"
76+
val mongoClient = MongoClient.create(uri)
77+
78+
Atlas
79+
~~~~~
80+
81+
The following code shows the connection string to connect to a
82+
deployment hosted on Atlas:
83+
84+
.. code-block:: kotlin
85+
86+
val uri = "mongodb+srv://<username>:<password>@<hostname/port>/?<options>"
87+
val mongoClient = MongoClient.create(uri)
88+
89+
Replica Set
90+
~~~~~~~~~~~
91+
92+
The following code shows the connection string to connect to a
93+
replica set:
94+
95+
.. code-block:: kotlin
96+
97+
val uri = "mongodb://<replica set member>:<port>/?replicaSet=<replica set name>"
98+
val mongoClient = MongoClient.create(uri)
99+
100+
Transport Layer Security (TLS)
101+
------------------------------
102+
103+
The following sections describe how to connect to MongoDB
104+
while enabling the TLS protocol.
105+
106+
Enable TLS
107+
~~~~~~~~~~
108+
109+
The following tabs demonstrate how to enable TLS on a connection:
110+
111+
.. include:: /includes/connect/tls-tabs.rst
112+
113+
.. To learn more about enabling TLS, see :ref:`kotlin-sync-enable-tls` in
114+
.. the TLS configuration guide.
115+
116+
Disable Hostname Verification
117+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
118+
119+
The following tabs demonstrate how to disable hostname verification when
120+
connecting by using TLS:
121+
122+
.. include:: /includes/connect/disable-host-verification-tabs.rst
123+
124+
.. To learn more about disabling hostname verification, see :ref:`kotlin-sync-insecure-tls` in
125+
.. the TLS configuration guide.
126+
127+
Network Compression
128+
-------------------
129+
130+
The following sections describe how to connect to MongoDB
131+
while specifying network compression algorithms.
132+
133+
Compression Algorithms
134+
~~~~~~~~~~~~~~~~~~~~~~
135+
136+
The following tabs demonstrate how to specify all available compressors
137+
while connecting to MongoDB:
138+
139+
.. include:: /includes/connect/compression-tabs.rst
140+
141+
.. To learn more about specifying compression algorithms, see
142+
.. :ref:`kotlin-sync-enable-compression` in the Network Compression guide.
143+
144+
zlib Compression Level
145+
~~~~~~~~~~~~~~~~~~~~~~
146+
147+
The following tabs demonstrate how to specify a compression level for
148+
the ``zlib`` compressor:
149+
150+
.. include:: /includes/connect/zlib-level-tabs.rst
151+
152+
.. To learn more about setting the zlib compression level, see
153+
.. :ref:`kotlin-sync-enable-compression` in the Network Compression guide.
154+
155+
Server Selection
156+
----------------
157+
158+
The following code shows a connection string that specifies a server
159+
selection function:
160+
161+
.. code-block:: kotlin
162+
163+
val client = MongoClient.create("mongodb://<username>:<password>@<hostname>:<port>",
164+
server_selector=<selector function>)
165+
166+
.. To learn more about customizing server selection, see
167+
.. :ref:`kotlin-sync-server-selection`.
168+
169+
{+stable-api+}
170+
--------------
171+
172+
The following code shows how to specify Stable API settings within a
173+
``MongoClientSettings`` instance:
174+
175+
.. code-block:: kotlin
176+
177+
val serverApi = ServerApi.builder()
178+
.version(ServerApiVersion.V1)
179+
.build()
180+
181+
val uri = "<connection string>"
182+
183+
val settings = MongoClientSettings.builder()
184+
.applyConnectionString(ConnectionString(uri))
185+
.serverApi(serverApi)
186+
.build()
187+
188+
val client = MongoClient.create(settings)
189+
190+
.. To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`.

‎source/includes/connect/compression-tabs.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
.. tabs::
2+
3+
.. tab:: MongoClient
4+
:tabid: mongoclient
5+
6+
.. code-block:: kotlin
7+
8+
val settings = MongoClientSettings.builder()
9+
.applyConnectionString(ConnectionString("<connection string>"))
10+
.compressorList(
11+
listOf(
12+
MongoCompressor.createSnappyCompressor(),
13+
MongoCompressor.createZlibCompressor(),
14+
MongoCompressor.createZstdCompressor())
15+
)
16+
.build()
17+
18+
val mongoClient = MongoClient.create(settings)
19+
20+
.. tab:: Connection String
21+
:tabid: connectionstring
22+
23+
.. code-block:: kotlin
24+
25+
val uri = ConnectionString("mongodb+srv://<user>:<password>@<cluster-url>/?compressors=snappy,zlib,zstd")
26+
27+
val mongoClient = MongoClient.create(uri)

‎source/includes/connect/disable-host-verification-tabs.rst

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
.. tabs::
2+
3+
.. tab:: MongoClient
4+
:tabid: mongoclient
5+
6+
.. code-block:: kotlin
7+
8+
val settings = MongoClientSettings.builder()
9+
.applyConnectionString(ConnectionString("<connection string>"))
10+
.applyToSslSettings { builder ->
11+
builder.enabled(true)
12+
builder.invalidHostNameAllowed(true)
13+
}
14+
.build()
15+
val mongoClient = MongoClient.create(settings);
16+
17+
18+
.. tab:: Connection String
19+
:tabid: connectionstring
20+
21+
.. code-block:: kotlin
22+
23+
val uri = "mongodb://<username>:<password>@<hostname>:<port>/?"tls=true&tlsAllowInvalidHostnames=true"
24+
val mongoClient = MongoClient.create(uri)

‎source/includes/connect/tls-tabs.rst

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
.. tabs::
2+
3+
.. tab:: MongoClient
4+
:tabid: mongoclient
5+
6+
.. code-block:: kotlin
7+
8+
val settings = MongoClientSettings.builder()
9+
.applyConnectionString(ConnectionString("<connection string>"))
10+
.applyToSslSettings { builder ->
11+
builder.enabled(true)
12+
}
13+
.build()
14+
15+
val mongoClient = MongoClient.create(settings)
16+
17+
18+
.. tab:: Connection String
19+
:tabid: connectionstring
20+
21+
.. code-block:: kotlin
22+
23+
val uri = "mongodb+srv://<user>:<password>@<cluster-url>?tls=true"
24+
val mongoClient = MongoClient.create(uri)

‎source/includes/connect/zlib-level-tabs.rst

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
.. tabs::
2+
3+
.. tab:: MongoClient
4+
:tabid: mongoclient
5+
6+
.. code-block:: kotlin
7+
8+
val zlib = MongoCompressor.createZlibCompressor()
9+
10+
val settings = MongoClientSettings.builder()
11+
.applyConnectionString(ConnectionString(uri))
12+
.compressorList(listOf(zlib.withProperty(MongoCompressor.LEVEL, <level>)))
13+
.build()
14+
15+
val mongoClient = MongoClient.create(settings)
16+
17+
.. tab:: Connection String
18+
:tabid: connectionstring
19+
20+
.. code-block:: kotlin
21+
22+
val uri = "mongodb://<username>:<password>@<hostname>:<port>/?" +
23+
"compressors=zlib" +
24+
"zlibCompressionLevel=<zlib compression level>"
25+
26+
val mongoClient = MongoClient.create(uri)

‎source/includes/usage-examples/connect-sample-app.kt

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
import com.mongodb.kotlin.client.MongoClient
2+
import org.bson.Document
3+
4+
fun main() {
5+
6+
// Start example code here
7+
8+
// End example code here
9+
10+
val database = mongoClient.getDatabase("admin")
11+
12+
val command = Document("ping", 1)
13+
val commandResult = database.runCommand(command)
14+
println("Pinged your deployment. You successfully connected to MongoDB!")
15+
}

‎source/index.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313

1414
.. toctree::
1515

16+
/connect
1617
/write-operations
1718
/read
1819
/indexes
@@ -47,6 +48,12 @@ Quick Start
4748
Learn how to establish a connection to MongoDB Atlas and begin
4849
working with data in the :ref:`Quick Start <kotlin-sync-quick-start>` section.
4950

51+
Connect to MongoDB
52+
------------------
53+
54+
Learn how to create and configure a connection to a MongoDB deployment
55+
in the :ref:`kotlin-sync-connect` section.
56+
5057
What's New
5158
----------
5259

0 commit comments

Comments
 (0)