Skip to content

Commit 5b290a2

Browse files
rustagirrustagir
authored
DOCSP-41123: cxn options (mongodb#40)
* DOCSP-41123: connection options * fix * fix * wip * MM suggestion * RL tech PR fixes 1 * spacing fix
1 parent ef426ee commit 5b290a2

File tree

2 files changed

+336
-7
lines changed

2 files changed

+336
-7
lines changed

‎source/connect.txt

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,10 +39,11 @@ This page contains code examples that show how to use the
3939
{+driver-short+} to connect your application to MongoDB by specifying
4040
various settings.
4141

42-
.. .. tip::
43-
..
44-
.. To learn more about the connection options on this page, see the link
45-
.. provided in each section.
42+
.. tip:: Connection Options
43+
44+
To learn more about the connection options on this page, see the link
45+
provided in each section. You can also view the
46+
:ref:`kotlin-sync-connection-options` guide to learn more.
4647

4748
To use a connection example from this page, copy the code example into the
4849
:ref:`sample application <kotlin-sync-connect-sample>` or your own application.
@@ -189,4 +190,4 @@ The following code shows how to specify Stable API settings within a
189190

190191
val client = MongoClient.create(settings)
191192

192-
.. To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`.
193+
To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`.

‎source/connect/connection-options.txt

Lines changed: 330 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Specify Connection Options
77
.. contents:: On this page
88
:local:
99
:backlinks: none
10-
:depth: 1
10+
:depth: 2
1111
:class: singlecol
1212

1313
.. facet::
@@ -18,4 +18,332 @@ Specify Connection Options
1818
:keywords: connection string, URI, server, Atlas, settings, configure
1919

2020
Overview
21-
--------
21+
--------
22+
23+
This section describes the MongoDB connection and authentication options
24+
available in the {+driver-short+}. You can configure your connection by
25+
setting options in either the connection URI or within a
26+
``MongoClientSettings`` instance.
27+
28+
.. _kotlin-sync-connection-uri-settings:
29+
30+
Set Options in the Connection URI
31+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32+
33+
If you pass a connection URI to the ``MongoClient.create()`` method, you can include
34+
connection options in the string as ``<name>=<value>`` pairs. In the following example,
35+
the connection URI contains the ``connectTimeoutMS`` option with a value of ``60000``
36+
and the ``tls`` option with a value of ``true``:
37+
38+
.. code-block:: kotlin
39+
40+
val uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true"
41+
val mongoClient = MongoClient.create(uri)
42+
43+
.. _kotlin-sync-mongoclientsettings:
44+
45+
Set Options in MongoClientSettings
46+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47+
48+
You can set connection options in a ``MongoClientSettings`` instance by
49+
using methods from the ``MongoClientSettings.Builder`` class, then passing
50+
the settings object to the ``MongoClient.create()`` method.
51+
52+
Configuring the connection this way makes it easier to
53+
change settings at runtime and can help you catch errors at compile time.
54+
55+
The following example shows how to specify your connection target and
56+
set other options when creating a ``MongoClientSettings`` instance:
57+
58+
.. code-block:: kotlin
59+
60+
val settings = MongoClientSettings.builder()
61+
.applyToClusterSettings { builder -> builder.hosts(listOf(ServerAddress("localhost", 27017))) }
62+
.applyToSocketSettings { builder -> builder.connectTimeout(60000, TimeUnit.MILLISECONDS) }
63+
.applyToSslSettings { builder -> builder.enabled(true) }
64+
.build()
65+
66+
val mongoClient = MongoClient.create(settings)
67+
68+
If you prefer to provide a connection string instead of specifying
69+
the hostname and port, you can use the ``applyConnectionString()``
70+
method, then set other options by using builder methods, as shown in the
71+
following code:
72+
73+
.. code-block:: kotlin
74+
:emphasize-lines: 1, 3
75+
76+
val uri = "<connection string>"
77+
val settings = MongoClientSettings.builder()
78+
.applyConnectionString(ConnectionString(uri))
79+
.applyToSocketSettings { builder -> builder.connectTimeout(60000, TimeUnit.MILLISECONDS) }
80+
.applyToSslSettings { builder -> builder.enabled(true) }
81+
.build()
82+
83+
val mongoClient = MongoClient.create(settings)
84+
85+
Connection Options
86+
------------------
87+
88+
The following sections describe the connection options available in the
89+
{+driver-short+}. Each option shows the option-value pair you can use in a
90+
connection URI and, if available, the driver method to set it within a
91+
``MongoClientSettings`` instance.
92+
93+
Network Compression
94+
~~~~~~~~~~~~~~~~~~~
95+
96+
.. list-table::
97+
:header-rows: 1
98+
:widths: 30 70
99+
100+
* - Connection Option
101+
- Description
102+
103+
* - **compressors**
104+
- | The preferred compression types, in order, for wire-protocol messages sent to
105+
or received from the server. The driver uses the first of these compression types
106+
that the server supports.
107+
|
108+
| **Data Type**: comma-delimited string
109+
| **MongoClientSettings**: ``compressorList(listOf(<MongoCompressor>))``
110+
| **Connection URI**: ``compressors=snappy,zstd,zlib``
111+
112+
* - **zlibCompressionLevel**
113+
- | The compression level for zlib to use. This option accepts
114+
an integer value between ``-1`` and ``9``, corresponding to the
115+
following settings:
116+
|
117+
| - **-1:** (Default). zlib uses its default compression level (usually ``6``).
118+
| - **0:** No compression.
119+
| - **1:** Fastest speed but lowest compression.
120+
| - **9:** Best compression but slowest speed.
121+
|
122+
| **Data Type**: integer
123+
| **Default**: ``-1``
124+
| **MongoClientSettings**: ``compressorList(listOf(zlib.withProperty(MongoCompressor.LEVEL, 3)))``
125+
| **Connection URI**: ``zlibCompressionLevel=3``
126+
127+
Timeouts
128+
~~~~~~~~
129+
130+
.. list-table::
131+
:header-rows: 1
132+
:widths: 30 70
133+
134+
* - Connection Option
135+
- Description
136+
137+
* - **connectTimeoutMS**
138+
- | The time in milliseconds to attempt a connection before timing out.
139+
|
140+
| **Data Type**: integer
141+
| **Default**: ``10000``
142+
| **MongoClientSettings**:
143+
144+
.. code-block:: kotlin
145+
146+
applyToSocketSettings{ builder ->
147+
builder.connectTimeout(10, TimeUnit.SECONDS)
148+
}
149+
150+
| **Connection URI**: ``timeoutMs=10000``
151+
152+
* - **socketTimeoutMS**
153+
- | The time in milliseconds to attempt a send or receive on a
154+
connection before the attempt times out.
155+
|
156+
| **Data Type**: integer
157+
| **Default**: no timeout
158+
| **MongoClientSettings**:
159+
160+
.. code-block:: kotlin
161+
162+
applyToSocketSettings{ builder ->
163+
builder.readTimeout(5, TimeUnit.SECONDS)
164+
}
165+
166+
| **Connection URI**: ``socketTimeoutMS=5000``
167+
168+
Server Selection
169+
~~~~~~~~~~~~~~~~
170+
171+
.. list-table::
172+
:header-rows: 1
173+
:widths: 30 70
174+
175+
* - Connection Option
176+
- Description
177+
178+
* - **serverSelectionTimeoutMS**
179+
- | The maximum amount of time, in milliseconds, the driver waits
180+
for server selection to succeed before throwing an
181+
exception.
182+
|
183+
| **Data Type**: integer
184+
| **Default**: ``30000``
185+
| **MongoClientSettings**:
186+
187+
.. code-block:: kotlin
188+
189+
applyToClusterSettings{ builder ->
190+
builder.serverSelectionTimeout(30, TimeUnit.SECONDS)
191+
}
192+
193+
| **Connection URI**: ``serverSelectionTimeoutMS=30000``
194+
195+
Authentication
196+
~~~~~~~~~~~~~~
197+
198+
.. TODO To learn more about authentication options, see the :ref:`kotlin-sync-auth` guide.
199+
200+
.. list-table::
201+
:header-rows: 1
202+
:widths: 30 70
203+
204+
* - Connection Option
205+
- Description
206+
207+
* - **authMechanism**
208+
- | The mechanism that the {+driver-short+} uses to authenticate
209+
the application.
210+
|
211+
| **Data Type**: string
212+
| **Default**: ``"SCRAM-SHA-256"`` when connecting to MongoDB
213+
v4.0 or later
214+
| **MongoClientSettings**:
215+
216+
.. code-block:: kotlin
217+
218+
credential(
219+
MongoCredential.createScramSha256Credential(...)
220+
)
221+
222+
| **Connection URI**: ``authMechanism=SCRAM-SHA-256``
223+
224+
* - **authMechanismProperties**
225+
- | Options specific to the authentication mechanism. This option
226+
isn't needed for all authentication mechanisms.
227+
|
228+
| **Data Type**: string
229+
| **Connection URI**: ``authMechanismProperties=AWS_SESSION_TOKEN:12435``
230+
231+
* - **authSource**
232+
- | The database to authenticate against.
233+
|
234+
| **Data Type**: string
235+
| **Default**: ``"admin"``
236+
| **Connection URI**: ``authSource=admin``
237+
238+
* - **username**
239+
- | The username for authentication. When this option is included in a connection
240+
URI, you must percent-encode it.
241+
|
242+
| **Data Type**: string
243+
| **Connection URI**: ``username=my+user``
244+
245+
* - **password**
246+
- | The password for authentication. When this option is included in a connection
247+
URI, you must percent-encode it.
248+
|
249+
| **Data Type**: string
250+
| **Connection URI**: ``password=strong+password``
251+
252+
Read and Write Operations
253+
~~~~~~~~~~~~~~~~~~~~~~~~~
254+
255+
To learn more about connecting to different types of MongoDB
256+
deployments, see the :ref:`kotlin-sync-connection-targets` guide.
257+
258+
.. list-table::
259+
:header-rows: 1
260+
:widths: 30 70
261+
262+
* - Connection Option
263+
- Description
264+
265+
* - **replicaSet**
266+
- | Specifies the name of the replica set to connect to.
267+
|
268+
| **Data Type**: string
269+
| **Connection URI**: ``replicaSet=myRS``
270+
271+
* - **directConnection**
272+
- | Whether to connect only to the primary member of the replica set.
273+
|
274+
| **Data Type**: boolean
275+
| **Default**: ``false``
276+
| **MongoClientSettings**:
277+
278+
.. code-block:: kotlin
279+
280+
applyToClusterSettings{ builder ->
281+
builder.mode(ClusterConnectionMode.SINGLE)
282+
}
283+
284+
| **Connection URI**: ``directConnection=true``
285+
286+
* - **readPreference**
287+
- | Specifies the client's read preference. For more information,
288+
see :manual:`Read Preference </core/read-preference/>` in the
289+
Server manual.
290+
|
291+
| **Data Type**: string
292+
| **Default**: ``primary``
293+
| **MongoClientSettings**: ``readPreference(ReadPreference.primary())``
294+
| **Connection URI**: ``readPreference=primary``
295+
296+
* - **readConcern**
297+
- | Specifies the client's read concern. For more information, see
298+
:manual:`Read Concern </reference/read-concern/>` in the Server
299+
manual.
300+
|
301+
| **Data Type**: string
302+
| **MongoClientSettings**: ``readConcern(ReadConcern.MAJORITY)``
303+
| **Connection URI**: ``readConcern=majority``
304+
305+
* - **writeConcern**
306+
- | Specifies the client's write concern. For more information, see
307+
:manual:`Write Concern </reference/write-concern/>` in the
308+
Server manual.
309+
|
310+
| **Data Type**: string
311+
| **MongoClientSettings**: ``writeConcern(WriteConcern.MAJORITY)``
312+
| **Connection URI**: ``writeConcern=majority``
313+
314+
* - **localThresholdMS**
315+
- | The latency window for a replica-set member's eligibility. If a member's
316+
round trip ping takes longer than the fastest server's round-trip ping
317+
time plus this value, the server isn't eligible for selection.
318+
|
319+
| **Data Type**: integer
320+
| **Default**: ``15``
321+
| **MongoClientSettings**:
322+
323+
.. code-block:: kotlin
324+
325+
applyToClusterSettings{ builder ->
326+
builder.localThreshold(35, TimeUnit.MILLISECONDS)
327+
}
328+
329+
| **Connection URI**: ``localThresholdMS=35``
330+
331+
Additional Information
332+
----------------------
333+
334+
To view a full list of connection options, see
335+
:manual:`Connection Strings </reference/connection-string/>` in the
336+
Server manual.
337+
338+
API Documentation
339+
~~~~~~~~~~~~~~~~~
340+
341+
To learn more about the classes and methods mentioned in this guide, see
342+
the following API documentation:
343+
344+
- `MongoClientSettings <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__
345+
- `MongoClientSettings.Builder <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__
346+
- `ConnectionString <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__
347+
- `SocketSettings <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/connection/SocketSettings.html>`__
348+
- `ClusterSettings <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/connection/ClusterSettings.html>`__
349+
- `MongoCredential <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__

0 commit comments

Comments
 (0)