Skip to content

Commit 4b67d36

Browse files
mcmorisimcmorisi
committed
DOCSP-41122: Choose a Connection Target (#33)
(cherry picked from commit 89f8076)
1 parent 14ae792 commit 4b67d36

File tree

3 files changed

+364
-0
lines changed

3 files changed

+364
-0
lines changed

‎source/connect.txt

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

‎source/connect/connection-targets.txt

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
.. _kotlin-sync-connection-targets:
2+
3+
==========================
4+
Choose a Connection Target
5+
==========================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: connection string, URI, server, settings, client
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use a connection string and a ``MongoClient`` object
24+
to connect to different types of MongoDB deployments.
25+
26+
Atlas
27+
-----
28+
29+
To connect to a MongoDB deployment on Atlas, include the following elements
30+
in your connection string:
31+
32+
- The URL of your Atlas cluster
33+
- Your MongoDB username
34+
- Your MongoDB password
35+
36+
Then, pass your connection string to the ``MongoClient`` constructor.
37+
38+
.. tip::
39+
40+
Follow the :atlas:`Atlas driver connection guide </driver-connection>`
41+
to retrieve your connection string.
42+
43+
When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid
44+
breaking changes when Atlas upgrades to a new version of {+mdb-server+}.
45+
To learn more about the {+stable-api+} feature, see the :ref:`<kotlin-sync-stable-api>`
46+
guide.
47+
48+
The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The
49+
code also uses the ``serverApi()`` method to specify a {+stable-api+} version.
50+
51+
.. literalinclude:: /includes/connect/connection-targets.kt
52+
:language: kotlin
53+
:start-after: start-connect
54+
:end-before: end-connect
55+
:dedent:
56+
57+
Local Deployments
58+
-----------------
59+
60+
To connect to a local MongoDB deployment, use ``localhost`` as the hostname. By
61+
default, the ``mongod`` process runs on port 27017, though you can customize this for
62+
your deployment.
63+
64+
The following code shows how to use the {+driver-short+} to connect to a local MongoDB
65+
deployment:
66+
67+
.. literalinclude:: /includes/connect/connection-targets.kt
68+
:language: kotlin
69+
:start-after: start-connect-local
70+
:end-before: end-connect-local
71+
:dedent:
72+
73+
Replica Sets
74+
------------
75+
76+
To connect to a replica set, specify the hostnames (or IP addresses) and
77+
port numbers of the replica-set members.
78+
79+
If you aren't able to provide a full list of hosts in the replica set, you can
80+
specify one or more of the hosts in the replica set and instruct the {+driver-short+} to
81+
perform automatic discovery to find the others. To instruct the driver to perform
82+
automatic discovery, perform one of the following actions:
83+
84+
- Specify the name of the replica set as the value of the ``replicaSet`` parameter.
85+
- Specify ``false`` as the value of the ``directConnection`` parameter.
86+
- Specify more than one host in the replica set.
87+
88+
The following examples show how to connect to a MongoDB replica set running on port
89+
``27017`` of three different hosts by using either the ``ConnectionString`` or
90+
``MongoClientSettings`` class. Select the tab that corresponds to your preferred class.
91+
92+
.. tabs::
93+
94+
.. tab:: ConnectionString
95+
:tabid: connectionstring
96+
97+
.. literalinclude:: /includes/connect/connection-targets.kt
98+
:language: kotlin
99+
:start-after: start-connect-rs-connection-string
100+
:end-before: end-connect-rs-connection-string
101+
:dedent:
102+
103+
.. tab:: MongoClientSettings
104+
:tabid: mongoclientsettings
105+
106+
.. literalinclude:: /includes/connect/connection-targets.kt
107+
:language: kotlin
108+
:start-after: start-connect-rs-settings
109+
:end-before: end-connect-rs-settings
110+
:dedent:
111+
112+
.. note::
113+
114+
The ``MongoClient`` constructor is *non-blocking*.
115+
When you connect to a replica set, the constructor returns immediately while the
116+
client uses background threads to connect to the replica set.
117+
118+
If you construct a ``MongoClient`` and immediately print the string representation
119+
of its ``nodes`` attribute, the list might be empty while the client connects to
120+
the replica-set members.

‎source/includes/connect/connection-targets.kt

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
package org.example
2+
import com.mongodb.ConnectionString
3+
import com.mongodb.MongoClientSettings
4+
import com.mongodb.ServerAddress
5+
import com.mongodb.ServerApi
6+
import com.mongodb.ServerApiVersion
7+
import com.mongodb.kotlin.client.MongoClient
8+
9+
fun main() {
10+
// start-connect
11+
// Defines Stable API version
12+
val serverApi = ServerApi.builder()
13+
.version(ServerApiVersion.V1)
14+
.build()
15+
16+
// Uses MongoClientSettings to apply connection string and specify the Stable API version
17+
val settings = MongoClientSettings.builder()
18+
.applyConnectionString("<connection string URI>")
19+
.serverApi(serverApi)
20+
.build()
21+
22+
val mongoClient = MongoClient.create(settings)
23+
// end-connect
24+
25+
// start-connect-local
26+
val settings = MongoClientSettings.builder()
27+
.applyConnectionString("mongodb://localhost:27017")
28+
.build()
29+
30+
val mongoClient = MongoClient.create(settings)
31+
// end-connect-local
32+
33+
// start-connect-rs-connection-string
34+
val mongoClient = MongoClient.create("mongodb://host1:27017,host2:27017,host3:27017/")
35+
// end-connect-rs-connection-string
36+
37+
// start-connect-rs-settings
38+
val hosts = listOf(
39+
ServerAddress("host1", 27017),
40+
ServerAddress("host2", 27017),
41+
ServerAddress("host3", 27017)
42+
)
43+
44+
val settings = MongoClientSettings.builder()
45+
.applyToClusterSettings { builder ->
46+
builder.hosts(hosts)
47+
}
48+
.build()
49+
50+
val mongoClient = MongoClient.create(settings)
51+
// end-connect-rs-settings
52+
}
53+

0 commit comments

Comments
 (0)