Skip to content

Commit f6bf5ea

Browse files
pierwillrustagir
pierwill
and
rustagir
authored
DOCSP-30524 Fundamentals > Connection Guide > Connection Options (#27)
Co-authored-by: pierwill <[email protected]> Co-authored-by: Rea Rustagi <[email protected]>
1 parent 487d205 commit f6bf5ea

File tree

2 files changed

+208
-3
lines changed

2 files changed

+208
-3
lines changed

‎source/fundamentals/connections.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@ Connections
77
.. toctree::
88

99
/fundamentals/connections/connection-guide
10+
/fundamentals/connections/connection-options
1011
/fundamentals/connections/network-compression
1112

1213
..
13-
/fundamentals/connections/connection-options
1414
/fundamentals/connections/tls
1515
Connect to MongoDB Atlas from AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
1616

@@ -27,13 +27,13 @@ Learn how to configure your application's connection to a MongoDB
2727
deployment using the {+driver-short+} in the following sections:
2828

2929
- :ref:`Connection Guide <rust-connect-to-mongodb>`
30+
- :ref:`Connection Options <rust-connection-options>`
3031
- :ref:`Enable Network Compression <rust-network-compression>`
3132

32-
.. - :ref:`Connection Options <rust-connection-options>`
3333
.. - :ref:`Enable TLS on a Connection <rust-connect-tls>`
3434
.. - :atlas:`Connect to MongoDB Atlas from AWS Lambda </manage-connections-aws-lambda/>`
3535

3636
.. To learn how to authenticate to MongoDB, see the following pages:
3737

3838
.. - :ref:`rust-authentication-mechanisms`
39-
.. - :ref:`rust-enterprise-authentication-mechanisms`
39+
.. - :ref:`rust-enterprise-authentication-mechanisms`

‎source/fundamentals/connections/connection-options.txt

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
.. _rust-connection-options:
2+
3+
==================
4+
Connection Options
5+
==================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
In this guide, you can learn about MongoDB connection and authentication
14+
options. You can pass connection options as parameters of the connection
15+
string URI to specify the behavior of the client. To learn more about connection strings, see
16+
:manual:`Connection Strings </reference/connection-string>` in the Server manual.
17+
18+
.. TODO link to the authentication mechanisms guide in authMechanism below
19+
.. (https://github.com/mongodb/docs-rust/pull/29)
20+
21+
.. list-table::
22+
:header-rows: 1
23+
:widths: 30 12 12 46
24+
25+
* - Option Name
26+
- Accepted Values
27+
- Default Value
28+
- Description
29+
30+
* - **appName**
31+
- String
32+
- None
33+
- Specifies the application name that the ``Client`` instance sends to the server as part of the handshake.
34+
Specifying an ``appName`` can help you use the server logs to determine which ``Client`` instance is connected
35+
to the server.
36+
37+
* - **authMechanism**
38+
- String
39+
- None
40+
- Specifies which authentication mechanism to use.
41+
If you do not specify this option, the driver uses the default authentication mechanism.
42+
43+
* - **authMechanismProperties**
44+
- String
45+
- None
46+
- Specifies additional properties for the authentication mechanism set in the ``authMechanism`` option.
47+
specified in the ``authMechanism`` option.
48+
49+
* - **authSource**
50+
- String
51+
- See description
52+
- Specifies the database used to authenticate.
53+
This option defaults to ``admin`` for SCRAM-based authentication mechanisms,
54+
``$external`` for the ``MONGODB-X509`` mechanism, and the database name or
55+
``$external`` for the ``PLAIN`` mechanism.
56+
57+
* - **compressors**
58+
- A comma-separated list of strings
59+
- None
60+
- Specifies compressors that the ``Client`` instance uses in the specified order.
61+
To learn more about network compression, see the :ref:`rust-network-compression` guide.
62+
63+
* - ***connectTimeoutMS***
64+
- Non-negative integer
65+
- ``10000`` (10 seconds)
66+
- Specifies the connection timeout, in milliseconds, passed to each underlying TCP stream when attempting to connect to the server.
67+
68+
* - **direct**
69+
- Boolean
70+
- ``false``
71+
- Specifies whether the ``Client`` instance directly connects to a single host
72+
instead of discovering and connecting to all of the servers in the cluster.
73+
74+
* - **heartbeatFrequencyMS**
75+
- Integer greater than or equal to 500
76+
- ``10000`` (10 seconds)
77+
- Specifies the amount of time, in milliseconds, that each monitoring thread waits between performing server checks.
78+
79+
* - **journal**
80+
- Boolean
81+
- ``false``
82+
- Requests acknowledgment that the operation propagated to the on-disk journal.
83+
84+
* - **localThresholdMS**
85+
- Non-negative integer
86+
- 15
87+
- Specifies how much longer, in milliseconds, that the average round trip time between the driver and server can take
88+
compared to the shortest round trip time of all the suitable servers.
89+
A value of ``0`` indicates that there is no latency window, so only the server with the lowest average round trip time is eligible.
90+
91+
* - **maxIdleTimeMS**
92+
- Non-negative integer
93+
- 0
94+
- Specifies the amount of time, in milliseconds, that a connection can remain idle in a connection pool the server closes it.
95+
A value of ``0`` indicates that the client does not close idle connections.
96+
97+
* - **maxStalenessSeconds**
98+
- ``-1``, or any integer greater than or equal to ``90``
99+
- ``-1``
100+
- Specifies the maximum lag, in seconds, behind the primary node that a secondary node can be to be
101+
considered for the given operation.
102+
103+
The value of this option must be at least ``90``, or the operation raises an error.
104+
A value of ``-1`` means there is no maximum lag.
105+
106+
* - **maxPoolSize**
107+
- Non-negative integer
108+
- ``10``
109+
- Specifies the maximum number of connections that the ``Client`` instance can create in a connection pool for a given server.
110+
If you attempt an operation while the value of ``maxPoolSize`` connections are checked out,
111+
the operation waits until an in-progress operation finishes and the connection returns to the pool.
112+
113+
* - **minPoolSize**
114+
- Non-negative integer
115+
- ``0``
116+
- Specifies the minimum number of connections that are available in a server's connection pool at a given time.
117+
If fewer than ``minPoolSize`` connections are in the pool,
118+
the server adds connections in the background up to the value of ``minPoolSize``.
119+
120+
* - **readConcernLevel**
121+
- String
122+
- None
123+
- Specifies the default read concern for operations performed on the ``Client`` instance.
124+
To learn more, see :manual:`Read Concern </reference/read-concern/>` in the Server manual.
125+
126+
* - **readPreference**
127+
- String
128+
- ``primary``
129+
- Specifies how the driver routes a read operation to members of a replica set.
130+
To learn more, see :manual:`Read Preference </core/read-preference>` in the Server manual.
131+
132+
* - **readPreferenceTags**
133+
- A list of comma-separated key-value pairs
134+
- None
135+
- Specifies which replica set members are considered for operations.
136+
Each instance of this key is a separate tag set.
137+
The driver checks each tag set until it finds one or more servers with each tag in the set.
138+
139+
* - **replicaSet**
140+
- String
141+
- None
142+
- Specifies the name of the replica set that the ``Client`` instance connects to.
143+
144+
* - **retryReads**
145+
- Boolean
146+
- ``true``
147+
- Specifies whether the client retries a read operation if the operation fails.
148+
149+
* - **serverSelectionTimeoutMS**
150+
- Non-negative integer
151+
- ``30000`` (30 seconds)
152+
- Specifies the amount of time, in milliseconds, that the ``Client`` instance waits when attempting to select a server for an operation before timing out.
153+
154+
* - **tls**
155+
- Boolean
156+
- ``false``
157+
- Specifies the TLS configuration for the ``Client`` instance to use in its connections with the server.
158+
By default, TLS is off.
159+
160+
* - **tlsAllowInvalidCertificates**
161+
- Boolean
162+
- ``true``
163+
- Specifies whether the ``Client`` instance returns an error if the server presents an invalid certificate.
164+
We recommend that you set this option to ``true`` only in testing environments to avoid creating vulnerabilities in your application.
165+
166+
* - **tlsCAFile**
167+
- String
168+
- See description
169+
- Specifies the path to the certificate authority (CA) file that the ``Client`` instance uses for TLS.
170+
If you do not specify this option, the driver uses the Mozilla root certificates from the ``webpki-roots`` crate.
171+
172+
* - **tlsCertificateKeyFile**
173+
- String
174+
- None
175+
- Specifies the path to the certificate file that the ``Client`` instance presents to the server to verify its identify.
176+
If you do not set this option, the ``Client`` instance does not attempt to verify its identity to the server.
177+
178+
* - **tlsInsecure**
179+
- Boolean
180+
- ``true``
181+
- Specifies whether the ``Client`` instance returns an error if the server presents an invalid certificate.
182+
We recommend that you set this option to ``true`` only in testing environments to avoid creating vulnerabilities in your application.
183+
184+
* - **w**
185+
- Non-negative integer or string
186+
- None
187+
- Requests acknowledgment that the operation has propagated to a specific number or variety of servers.
188+
To learn more, see :manual:`Write Concern </reference/write-concern>` in the Server manual.
189+
190+
* - **wTimeoutMS**
191+
- Non-negative integer
192+
- No timeout
193+
- Specifies a time limit, in milliseconds, for the write concern.
194+
If an operation has not propagated to the requested level within the time limit, the driver raises an error.
195+
196+
* - **zlibCompressionLevel**
197+
- Integer between -1 and 9 (inclusive)
198+
- ``-1``
199+
- Specifies the level field of the ``zlib`` compression if you use that compressor.
200+
Setting a value of``-1`` selects the default compression level (``6``).
201+
Setting a value of ``0`` specifies no compression, and setting a value of ``9`` specifies maximum
202+
compression.
203+
To learn more about network compression, see the :ref:`rust-network-compression` guide.
204+
205+
For a full list of options, see the `ClientOptions API documentation <{+api+}/options/struct.ClientOptions.html>`__.

0 commit comments

Comments
 (0)