Skip to content

Commit f3960dd

Browse files
lindseymoorelindseymoore
authored
DOCSP-45812 Connection Options (#132)
* DOCSP-45812 Connection Options * edits * more edits * more edits * format * format * RM review * another link * add timeout_ms * remove deprecated options
1 parent 51d497c commit f3960dd

File tree

2 files changed

+291
-0
lines changed

2 files changed

+291
-0
lines changed

‎source/connect.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,4 +25,5 @@ Connect to MongoDB
2525
Create a Client </connect/mongoclient>
2626
Stable API </connect/stable-api>
2727
Choose a Connection Target </connect/connection-targets>
28+
Connection Option </connect/connection-options>
2829
Configure TLS </connect/tls>

‎source/connect/connection-options.txt

Lines changed: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
.. _ruby-connection-options:
2+
3+
==========================
4+
Specify Connection Options
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+
:keywords: connection string, URI, server, Atlas, settings, configure
19+
20+
Overview
21+
--------
22+
23+
This section describes the MongoDB connection and authentication options
24+
available in {+driver-short+}. You can configure your connection by using either
25+
the connection URI (also called a :manual:`connection string </connection-string/>`)
26+
or by passing arguments to the ``Mongo::Client`` constructor.
27+
28+
Using the Connection URI
29+
~~~~~~~~~~~~~~~~~~~~~~~~
30+
31+
If you pass a connection URI to the ``Mongo::Client`` constructor, you can include
32+
connection options in the string as ``<name>=<value>`` pairs. In the following example,
33+
the connection URI contains the ``connectTimeoutMS`` option with a value of ``60000``
34+
and the ``tls`` option with a value of ``true``:
35+
36+
.. code-block:: ruby
37+
38+
uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true"
39+
client = Mongo::Client.new(uri)
40+
41+
Using a ``Mongo::Client``
42+
~~~~~~~~~~~~~~~~~~~~~~~~~
43+
44+
You can pass connection options as arguments to the ``Mongo::Client`` constructor
45+
instead of including them in your connection URI.
46+
When you configure your connection this way, it easier for you to
47+
change settings at runtime and catch errors during compilation.
48+
The following example shows how to use the ``Mongo::Client`` constructor to set
49+
connection options:
50+
51+
.. code-block:: ruby
52+
53+
uri = "mongodb://<hostname>:<port>"
54+
client = Mongo::Client.new(uri, connect_timeout: 60000, ssl: true)
55+
56+
Connection Options
57+
------------------
58+
59+
The following sections describe the connection options available in the {+driver-short+}.
60+
61+
Network Compression
62+
~~~~~~~~~~~~~~~~~~~
63+
64+
.. list-table::
65+
:header-rows: 1
66+
:widths: 30 70
67+
68+
* - Connection Option
69+
- Description
70+
71+
* - **:compressors**
72+
- | A list of potential compressors to use, in order of preference.
73+
The driver chooses the first compressor that is also supported
74+
by the server. Currently the driver only supports ``zstd``, ``snappy``, and ``zlib``.
75+
|
76+
| **Data Type**: ``Array<String>``
77+
| **Default**: none
78+
| **Client Example**: ``compressors: ['snappy', 'zstd', 'zlib']``
79+
| **Connection URI Example**: ``compressors=snappy,zstd,zlib``
80+
81+
* - **:zlib_compression_level**
82+
- | The Zlib compression level to use, if using compression.
83+
This option accepts an integer value between ``-1`` and ``9``:
84+
|
85+
| - **-1:** zlib uses its default compression level (usually ``6``).
86+
| - **0:** No compression.
87+
| - **1:** Fastest speed but lowest compression.
88+
| - **9:** Best compression but slowest speed.
89+
|
90+
| For more information, see Ruby's `ZLib module <https://ruby-doc.org/stdlib-2.7.0/libdoc/zlib/rdoc/Zlib.html>`__
91+
documentation.
92+
|
93+
| **Data Type**: ``Integer``
94+
| **Default**: ``None``
95+
| **Client Example**: ``zlib_compression_level: 3``
96+
| **Connection URI Example**: ``zlibCompressionLevel=3``
97+
98+
Timeouts
99+
~~~~~~~~
100+
101+
.. list-table::
102+
:header-rows: 1
103+
:widths: 30 70
104+
105+
* - Connection Option
106+
- Description
107+
108+
* - **:connect_timeout**
109+
- | The number of seconds to wait to establish a socket
110+
connection before raising an exception. This
111+
timeout is also used for SRV DNS record resolution.
112+
|
113+
| ``nil`` and ``0`` mean no timeout. Client creation will
114+
fail with an error if an invalid timeout value
115+
is passed (such as a negative value or a non-numeric value).
116+
|
117+
| **Data Type**: ``Float``
118+
| **Default**: ``10.0``
119+
| **Client Example**: ``connect_timeout: 10.0``
120+
| **Connection URI Example**: ``connectTimeoutMS=10000``
121+
122+
* - **:timeout_ms**
123+
- | The number of milliseconds to wait for an operation to execute
124+
before raising an exception.
125+
|
126+
| ``0`` means no timeout. Client creation will fail
127+
with an error if an invalid timeout value is passed
128+
(such as a negative value or a non-numeric value).
129+
|
130+
| **Data Type**: ``Integer``
131+
| **Default**: none
132+
| **Client Example**: ``timeout_ms: 5000``
133+
| **Connection URI Example**: ``timeoutMS=5000``
134+
135+
Server Selection
136+
~~~~~~~~~~~~~~~~
137+
138+
.. list-table::
139+
:header-rows: 1
140+
:widths: 30 70
141+
142+
* - Connection Option
143+
- Description
144+
145+
* - **:server_selector**
146+
- | Get the server selector. It either uses the read preference
147+
defined in the client options or defaults to a Primary
148+
server selector.
149+
|
150+
| **Data Type**: ``ServerSelector``
151+
| **Default**: none
152+
| **Client Example**: ``server_selector: { mode: :secondary_preferred }``
153+
| **Connection URI Example**: N/A
154+
155+
* - **:server_selection_timeout**
156+
- | The maximum amount of time, in seconds, the driver waits
157+
for server selection to succeed before throwing an exception.
158+
|
159+
| **Data Type**: ``Integer``
160+
| **Default**: ``30``
161+
| **Client Example**: ``server_selection_timeout: 30``
162+
| **Connection URI Example**: ``serverSelectionTimeoutMS=30000``
163+
164+
Authentication
165+
~~~~~~~~~~~~~~
166+
167+
.. list-table::
168+
:header-rows: 1
169+
:widths: 30 70
170+
171+
* - Connection Option
172+
- Description
173+
174+
* - **:auth_mech**
175+
- | The mechanism that the {+driver-short+} uses to authenticate the application.
176+
|
177+
| **Data Type**: ``Symbol``
178+
| **Default**: ``nil`` if user credentials are not supplied.
179+
| ``:scram256`` when connecting to MongoDB v4.0 or later.
180+
| **Client Example**: ``auth_mech: :scram256``
181+
| **Connection URI Example**: ``authMechanism=SCRAM-SHA-256``
182+
183+
* - **:auth_mech_properties**
184+
- | Options specific to the authentication mechanism. This option
185+
isn't needed for all authentication mechanisms.
186+
|
187+
| **Data Type**: ``Hash``
188+
| **Default**: When you use the GSSAPI authentication mechanism,
189+
| the default properties are ``{service_name: "mongodb"}``.
190+
| Otherwise, the default is ``nil``.
191+
| **Client Example**: ``auth_mech_properties: {aws_session_token: '12345'}``
192+
| **Connection URI Example**: ``authMechanismProperties=AWS_SESSION_TOKEN:12345``
193+
194+
* - **:auth_source**
195+
- | The database to authenticate against.
196+
|
197+
| **Data Type**: ``String``
198+
| **Default**: ``admin``, if credentials are supplied
199+
| **Client Example**: ``auth_source: admin``
200+
| **Connection URI Example**: ``authSource=admin``
201+
202+
* - **:user**
203+
- | The username for authentication. When this option is included
204+
in a connection URI, you must
205+
`percent-encode <https://datatracker.ietf.org/doc/html/rfc3986#section-2.1>`__ it.
206+
|
207+
| **Data Type**: ``String``
208+
| **Default**: none
209+
| **Client Example**: ``user: my+user``
210+
| **Connection URI Example**: ``username=my+user``
211+
212+
* - **:password**
213+
- | The password for authentication. When this option is included
214+
in a connection URI, you must
215+
`percent-encode <https://datatracker.ietf.org/doc/html/rfc3986#section-2.1>`__ it.
216+
|
217+
| **Data Type**: ``String``
218+
| **Default**: none
219+
| **Client Example**: ``password: strong+password``
220+
| **Connection URI Example**: ``password=strong+password``
221+
222+
Read and Write Operations
223+
~~~~~~~~~~~~~~~~~~~~~~~~~
224+
225+
.. list-table::
226+
:header-rows: 1
227+
:widths: 30 70
228+
229+
* - Connection Option
230+
- Description
231+
232+
* - **:replica_set**
233+
- | Specifies the name of the replica set to connect to.
234+
|
235+
| **Data Type**: ``String``
236+
| **Default**: none
237+
| **Client Example**: ``replica_set: 'myRS'``
238+
| **Connection URI Example**: ``replicaSet=myRS``
239+
240+
* - **:direct_connection**
241+
- | Whether to connect directly to the specified host
242+
|
243+
| **Data Type**: ``Boolean``
244+
| **Default**: ``false``
245+
| **Client Example**: ``direct_connection: true``
246+
| **Connection URI Example**: ``directConnection=true``
247+
248+
* - **:read**
249+
- | The read preference options. For more information,
250+
see :manual:`Read Preference </core/read-preference/>` in the Server manual.
251+
|
252+
| **Data Type**: ``Hash``
253+
| **Default**: ``{ :mode: :primary }``
254+
| **Client Example**: ``read: { mode: :primary }``
255+
| **Connection URI Example**: ``readPreference=primary``
256+
257+
* - **:read_concern**
258+
- | Specifies the read concern options. For more information, see
259+
:manual:`Read Concern </reference/read-concern/>` in the Server manual.
260+
|
261+
| **Data Type**: ``Hash``
262+
| **Default**: none
263+
| **Client Example**: ``read: { level: :majority }``
264+
| **Connection URI Example**: ``readConcern=majority``
265+
266+
* - **:write_concern**
267+
- | Specifies the client's write concern. For more
268+
information, see :manual:`Write Concern </reference/write-concern/>` in the Server manual.
269+
|
270+
| **Data Type**: ``Hash``
271+
| **Default**: ``write_concern: { w: 1 }``
272+
| **Client Example**: ``write_concern: { w: 2 }``
273+
| **Connection URI Example**: ``w=2``
274+
275+
* - **:local_threshold**
276+
- | The latency window, in seconds, for a replica-set member's
277+
eligibility. If a member's round trip ping takes longer
278+
than the fastest server's round-trip ping time
279+
plus this value, the server isn't eligible for selection.
280+
|
281+
| **Data Type**: ``Float``
282+
| **Default**: ``0.015``
283+
| **Client Example**: ``local_threshold: 0.020``
284+
| **Connection URI Example**: ``localThresholdMS=20``
285+
286+
API Documentation
287+
-----------------
288+
289+
For more information about ``Mongo::Client`` options for the {+driver-short+},
290+
see the API documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ .

0 commit comments

Comments
 (0)