Skip to content

Commit 8921a0f

Browse files
rustagirrustagir
committed
DOCSP-41123: connection options
1 parent d45f795 commit 8921a0f

File tree

2 files changed

+272
-6
lines changed

2 files changed

+272
-6
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.
@@ -188,4 +189,4 @@ The following code shows how to specify Stable API settings within a
188189

189190
val client = MongoClient.create(settings)
190191

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

‎source/connect/connection-options.txt

Lines changed: 266 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,269 @@ 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 set options when creating a
56+
``MongoClientSettings`` instance:
57+
58+
.. code-block:: kotlin
59+
60+
val uri = "<connection string>"
61+
62+
val settings = MongoClientSettings.builder()
63+
.applyConnectionString(ConnectionString(uri))
64+
.retryWrites(true)
65+
.build()
66+
67+
val mongoClient = MongoClient.create(settings)
68+
69+
Connection Options
70+
------------------
71+
72+
The following sections describe the connection options available in the
73+
{+driver-short+}. Each option shows the option-value pair you can use in a
74+
connection URI and the builder method to set it within a
75+
``MongoClientSettings`` instance.
76+
77+
Network Compression
78+
~~~~~~~~~~~~~~~~~~~
79+
80+
.. list-table::
81+
:header-rows: 1
82+
:widths: 30 70
83+
84+
* - Connection Option
85+
- Description
86+
87+
* - **compressors**
88+
- | The preferred compression types, in order, for wire-protocol messages sent to
89+
or received from the server. The driver uses the first of these compression types
90+
that the server supports.
91+
|
92+
| **Data Type**: Comma-delimited string of compressors
93+
| **MongoClientSettings**: ``compressorList(listOf(<MongoCompressor>))``
94+
| **Connection URI**: ``compressors=snappy,zstd,zlib``
95+
96+
* - **zlibCompressionLevel**
97+
- | The compression level for zlib to use. This option accepts
98+
an integer value between ``-1`` and ``9``, corresponding to the
99+
following settings:
100+
|
101+
| - **-1:** (Default). zlib uses its default compression level (usually ``6``).
102+
| - **0:** No compression.
103+
| - **1:** Fastest speed but lowest compression.
104+
| - **9:** Best compression but slowest speed.
105+
|
106+
| **Data Type**: integer
107+
| **Default**: ``-1``
108+
| **MongoClientSettings**: ``compressorList(listOf(zlib.withProperty(MongoCompressor.LEVEL, 3)))``
109+
| **Connection URI**: ``zlibCompressionLevel=3``
110+
111+
Timeouts
112+
~~~~~~~~
113+
114+
.. list-table::
115+
:header-rows: 1
116+
:widths: 30 70
117+
118+
* - Connection Option
119+
- Description
120+
121+
* - **connectTimeoutMS**
122+
- | The time in milliseconds to attempt a connection before timing out.
123+
|
124+
| **Data Type**: integer
125+
| **Default**: ``10000``
126+
| **MongoClientSettings**: ``applyToSocketSettings{ builder -> builder.connectTimeout(10, TimeUnit.SECONDS)}``
127+
| **Connection URI**: ``timeoutMs=10000``
128+
129+
* - **socketTimeoutMS**
130+
- | The time in milliseconds to attempt a send or receive on a
131+
connection before the attempt times out.
132+
|
133+
| **Data Type**: integer
134+
| **Default**: no timeout
135+
| **MongoClientSettings**: ``applyToSocketSettings{ builder -> builder.readTimeout(5, TimeUnit.SECONDS)}``
136+
| **Connection URI**: ``socketTimeoutMS=5000``
137+
138+
Server Selection
139+
~~~~~~~~~~~~~~~~
140+
141+
.. list-table::
142+
:header-rows: 1
143+
:widths: 30 70
144+
145+
* - Connection Option
146+
- Description
147+
148+
* - **serverSelectionTimeoutMS**
149+
- | The maximum amount of time, in milliseconds, the driver waits
150+
for server selection to succeed before throwing an
151+
exception.
152+
|
153+
| **Data Type**: integer
154+
| **Default**: ``30000``
155+
| **MongoClientSettings**: ``applyToClusterSettings{ builder -> builder.serverSelectionTimeout(30, TimeUnit.SECONDS)}``
156+
| **Connection URI**: ``serverSelectionTimeoutMS=30000``
157+
158+
Authentication
159+
~~~~~~~~~~~~~~
160+
161+
.. TODO To learn more about authentication options, see the :ref:`kotlin-sync-auth` guide.
162+
163+
.. list-table::
164+
:header-rows: 1
165+
:widths: 30 70
166+
167+
* - Connection Option
168+
- Description
169+
170+
* - **authMechanism**
171+
- | The mechanism that the {+driver-short+} uses to authenticate
172+
the application.
173+
|
174+
| **Data Type**: string
175+
| **Default**: ``"SCRAM-SHA-256"`` when connecting to MongoDB
176+
v4.0 or later
177+
| **MongoClientSettings**: ``credential(MongoCredential.createScramSha256Credential(...))``
178+
| **Connection URI**: ``authMechanism=SCRAM-SHA-256``
179+
180+
* - **authMechanismProperties**
181+
- | Options specific to the authentication mechanism. This option
182+
isn't needed for all authentication mechanisms.
183+
|
184+
| **Data Type**: string
185+
| **Connection URI**: ``authMechanismProperties=AWS_SESSION_TOKEN:12435``
186+
187+
* - **authSource**
188+
- | The database to authenticate against.
189+
|
190+
| **Data Type**: string
191+
| **Default**: ``"admin"``
192+
| **Connection URI**: ``authSource=admin``
193+
194+
* - **username**
195+
- | The username for authentication. When this option is included in a connection
196+
URI, you must percent-encode it.
197+
|
198+
| **Data Type**: string
199+
| **Connection URI**: ``username=my+user``
200+
201+
* - **password**
202+
- | The password for authentication. When this option is included in a connection
203+
URI, you must percent-encode it.
204+
|
205+
| **Data Type**: string
206+
| **Connection URI**: ``password=strong+password``
207+
208+
Read and Write Operations
209+
~~~~~~~~~~~~~~~~~~~~~~~~~
210+
211+
To learn more about connecting to different types of MongoDB
212+
deployments, see the :ref:`kotlin-sync-connection-targets` guide.
213+
214+
.. list-table::
215+
:header-rows: 1
216+
:widths: 30 70
217+
218+
* - Connection Option
219+
- Description
220+
221+
* - **replicaSet**
222+
- | Specifies the name of the replica set to connect to.
223+
|
224+
| **Data Type**: string
225+
| **Connection URI**: ``replicaSet=myRS``
226+
227+
* - **directConnection**
228+
- | Whether to connect only to the primary member of the replica set.
229+
|
230+
| **Data Type**: boolean
231+
| **Default**: ``false``
232+
| **MongoClientSettings**: ``applyToClusterSettings{ builder -> builder.mode(ClusterConnectionMode.SINGLE) }``
233+
| **Connection URI**: ``directConnection=true``
234+
235+
* - **readPreference**
236+
- | Specifies the client's read preference. For more information, see :manual:`</core/read-preference/>`.
237+
|
238+
| **Data Type**: string
239+
| **Default**: ``primary``
240+
| **MongoClientSettings**: ``readPreference(ReadPreference.primary())``
241+
| **Connection URI**: ``readPreference=primary``
242+
243+
* - **readConcern**
244+
- | Specifies the client's read concern. For more information, see :manual:`</reference/read-concern/>`.
245+
|
246+
| **Data Type**: string
247+
| **MongoClientSettings**: ``readConcern(ReadConcern.MAJORITY)``
248+
| **Connection URI**: ``readConcern=majority``
249+
250+
* - **writeConcern**
251+
- | Specifies the client's write concern. For more information, see
252+
:manual:`</reference/write-concern/>`.
253+
|
254+
| **Data Type**: string
255+
| **MongoClientSettings**: ``writeConcern(WriteConcern.MAJORITY)``
256+
| **Connection URI**: ``writeConcern=majority``
257+
258+
* - **localThresholdMS**
259+
- | The latency window for a replica-set member's eligibility. If a member's
260+
round trip ping takes longer than the fastest server's round-trip ping
261+
time plus this value, the server isn't eligible for selection.
262+
|
263+
| **Data Type**: integer
264+
| **Default**: ``15``
265+
| **MongoClientSettings**: ``applyToClusterSettings{ builder -> builder.localThreshold(35, TimeUnit.MILLISECONDS) }``
266+
| **Connection URI**: ``localThresholdMS=35``
267+
268+
Additional Information
269+
----------------------
270+
271+
To view a full list of connection options, see
272+
:manual:`Connection Strings </reference/connection-string/>` in the
273+
Server manual.
274+
275+
API Documentation
276+
~~~~~~~~~~~~~~~~~
277+
278+
To learn more about the classes and methods mentioned in this guide, see
279+
the following API documentation:
280+
281+
- `MongoClientSettings <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__
282+
- `MongoClientSettings.Builder <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__
283+
- `ConnectionString <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__
284+
- `SocketSettings <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/connection/SocketSettings.html>`__
285+
- `ClusterSettings <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/connection/ClusterSettings.html>`__
286+
- `MongoCredential <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__

0 commit comments

Comments
 (0)