Skip to content

Commit e5fb735

Browse files
mongoKartmongoKart
committed
rm feedback
1 parent 1bf1b65 commit e5fb735

17 files changed

+653
-1350
lines changed

‎source/connect/connection-options.txt

Lines changed: 18 additions & 334 deletions
Original file line numberDiff line numberDiff line change
@@ -21,16 +21,19 @@ Specify Connection Options
2121
:titlesonly:
2222
:maxdepth: 1
2323

24+
Enable Authentication </security>
2425
Compress Network Traffic </connect/connection-options/network-compression>
2526
Customize Server Selection </connect/connection-options/server-selection>
2627
Stable API </connect/connection-options/stable-api>
2728
Limit Server Execution Time </connect/connection-options/csot>
29+
Connection Pools </connect/connection-options/connection-pools>
30+
Configure CRUD Operations </crud/configure>
2831

2932
Overview
3033
--------
3134

3235
This section describes the MongoDB connection and authentication options
33-
available in {+driver-short+}. You can configure your connection using either
36+
available in {+driver-short+}. You can configure your connection by using either
3437
the connection URI or arguments to the ``MongoClient`` constructor.
3538

3639
.. _pymongo-connection-uri:
@@ -68,340 +71,21 @@ connection options:
6871
Connection Options
6972
------------------
7073

71-
The following sections describe the connection options available in {+driver-short+}.
72-
If a ``MongoClient`` parameter maps to more than one
73-
option in the connection string, the **Connection URI Example** shows all
74-
relevant options.
74+
To learn about the connection options available in {+driver-short+}, see the following
75+
sections:
7576

76-
.. todo: .. note::
77-
If you're using a query parameter for a time duration, the value must be in
78-
milliseconds. For example, to specify 60 seconds, use the value ``60000``. If you're
79-
using a ``MongoClientSettings`` object for a time duration, use the appropriate
80-
``TimeSpan`` value.
77+
- :ref:`Enable Authentication <pymongo-security>`
78+
- :ref:`Compress Network Traffic <pymongo-network-compression>`
79+
- :ref:`Customize Server Selection <pymongo-server-selection>`
80+
- :ref:`Stable API <pymongo-stable-api>`
81+
- :ref:`Limit Server Execution Time <pymongo-csot>`
82+
- :ref:`Connection Pools <pymongo-connection-pools>`
83+
- :ref:`Configure CRUD Operations <pymongo-configure-crud>`
8184

82-
Network Compression
83-
~~~~~~~~~~~~~~~~~~~
85+
API Documentation
86+
-----------------
8487

85-
.. list-table::
86-
:header-rows: 1
87-
:widths: 30 70
88+
To learn more about creating a ``MongoClient`` object in {+driver-short+},
89+
see the following API documentation:
8890

89-
* - Connection Option
90-
- Description
91-
92-
* - ``compressors``
93-
- | The preferred compression types, in order, for wire-protocol messages sent to
94-
| or received from the server. The driver uses the first of these compression types
95-
| that the server supports.
96-
|
97-
| **Data Type**: {+string-data-type+}
98-
| **Default**: ``None``
99-
| **MongoClient Example**: ``compressors = "snappy,zstd,zlib"``
100-
| **Connection URI Example**: ``compressors=snappy,zstd,zlib``
101-
102-
* - ``zlibCompressionLevel``
103-
- | The compression level for zlib to use. This option accepts
104-
| an integer value between ``-1`` and ``9``:
105-
|
106-
| - **-1:** (Default). zlib uses its default compression level (usually ``6``).
107-
| - **0:** No compression.
108-
| - **1:** Fastest speed but lowest compression.
109-
| - **9:** Best compression but slowest speed.
110-
|
111-
| **Data Type**: {+int-data-type+}
112-
| **Default**: ``-1``
113-
| **MongoClient Example**: ``zlibCompressionLevel = 3``
114-
| **Connection URI Example**: ``zlibCompressionLevel=3``
115-
116-
For more information about network compression in {+driver-short+}, see
117-
:ref:`<pymongo-network-compression>`.
118-
119-
Server Selection
120-
~~~~~~~~~~~~~~~~
121-
122-
.. list-table::
123-
:header-rows: 1
124-
:widths: 30 70
125-
126-
* - Connection Option
127-
- Description
128-
129-
* - ``server_selector``
130-
- | A user-defined Python function called by {+driver-short+} to choose the server
131-
| to run an operation against. For more information, see
132-
| :ref:`<pymongo-server-selection>`.
133-
|
134-
| **Data Type**: ``callable``
135-
| **Default**: ``None``
136-
| **MongoClient Example**: ``server_selector = your_function``
137-
| **Connection URI Example**: N/A
138-
139-
Stable API
140-
~~~~~~~~~~
141-
142-
.. list-table::
143-
:header-rows: 1
144-
:widths: 30 70
145-
146-
* - Connection Option
147-
- Description
148-
149-
* - ``server_api``
150-
- | A ``ServerApi`` object that specifies the Stable API version and other Stable API
151-
| options.
152-
|
153-
| **Data Type**: ``ServerApi``
154-
| **Default**: ``None``
155-
| **MongoClient Example**: ``server_api = ServerApi("1")``
156-
| **Connection URI Example**: N/A
157-
158-
For more information about the Stable API, see :ref:`<pymongo-stable-api>`.
159-
160-
Timeouts
161-
~~~~~~~~
162-
163-
.. list-table::
164-
:header-rows: 1
165-
:widths: 30 70
166-
167-
* - Connection Option
168-
- Description
169-
170-
* - ``timeoutMS``
171-
- | The number of milliseconds each driver operation must complete within. If an
172-
| operation doesn't finish in the specified time, {+driver-short+} raises a timeout exception.
173-
| For more information, see :ref:`<pymongo-csot>`.
174-
|
175-
| **Data Type**: ``int``
176-
| **Default**: ``None``
177-
| **MongoClient Example**: ``timeoutMS = 10000``
178-
| **Connection URI Example**: ``timeoutMs=10000``
179-
180-
For more information about using timeouts to limit server execution time, see
181-
:ref:`<pymongo-csot>`.
182-
183-
Connection Pools
184-
~~~~~~~~~~~~~~~~
185-
186-
A **connection pool** is a cache of open database connections maintained by {+driver-short+}.
187-
When your application requests a connection to MongoDB, {+driver-short+}
188-
gets a connection from the pool, performs operations, and returns the connection
189-
to the pool for reuse. Connection pools help reduce application latency and the number
190-
of times that {+driver-short+} must create new connections.
191-
192-
To learn more about connection pools, see
193-
:manual:`Connection Pool Overview </administration/connection-pool-overview/>`
194-
in the {+mdb-server+} manual.
195-
196-
.. list-table::
197-
:widths: 30 70
198-
:header-rows: 1
199-
200-
* - Setting
201-
- Description
202-
203-
* - ``connectTimeoutMS``
204-
- | The time that {+driver-short+} waits when connecting a new
205-
socket before timing out.
206-
|
207-
| **Data Type**: ``int``
208-
| **Default**: ``20000``
209-
| **MongoClient Example**: ``connectTimeoutMS = 40000``
210-
| **Connection URI Example**: ``connectTimeoutMS=40000``
211-
212-
* - ``maxConnecting``
213-
- | The maximum number of connections that each pool can establish concurrently.
214-
If this limit is reached, further requests wait until a connection is established
215-
or another in-use connection is checked back into the pool.
216-
|
217-
| **Data Type**: ``int``
218-
| **Default**: ``2``
219-
| **MongoClient Example**: ``maxConnecting = 3``
220-
| **Connection URI Example**: ``maxConnecting=3``
221-
222-
* - ``maxIdleTimeMS``
223-
- | The maximum time that a connection can remain idle in the pool.
224-
|
225-
| **Data Type**: ``int``
226-
| **Default**: ``None`` (no limit)
227-
| **MongoClient Example**: ``maxIdleTimeMS = 60000``
228-
| **Connection URI Example**: ``maxIdleTimeMS=60000``
229-
230-
* - ``maxPoolSize``
231-
- | The maximum number of concurrent connections that the pool maintains.
232-
If the maximum pool size is reached, further requests wait until a connection
233-
becomes available.
234-
|
235-
| **Data Type**: ``int``
236-
| **Default**: ``100``
237-
| **MongoClient Example**: ``maxPoolSize = 150``
238-
| **Connection URI Example**: ``maxPoolSize=150``
239-
240-
* - ``minPoolSize``
241-
- | The minimum number of concurrent connections that the pool maintains. If
242-
the number of open connections falls below this value due to network errors,
243-
{+driver-short+} attempts to create new connections to maintain this minimum.
244-
|
245-
| **Data Type**: ``int``
246-
| **Default**: ``0``
247-
| **MongoClient Example**: ``minPoolSize = 3``
248-
| **Connection URI Example**: ``minPoolSize=3``
249-
250-
* - ``socketTimeoutMS``
251-
- | The length of time that {+driver-short+} waits for a response from the server
252-
before timing out.
253-
|
254-
| **Data Type**: ``int``
255-
| **Default**: ``None`` (no timeout)
256-
| **MongoClient Example**: ``socketTimeoutMS = 100000``
257-
| **Connection URI Example**: ``socketTimeoutMS=100000``
258-
259-
* - ``waitQueueTimeoutMS``
260-
- | How long a thread waits for a connection to become available in the connection pool
261-
before timing out.
262-
|
263-
| **Data Type**: ``int``
264-
| **Default**: ``None`` (no timeout)
265-
| **MongoClient Example**: ``waitQueueTimeoutMS = 100000``
266-
| **Connection URI Example**: ``waitQueueTimeoutMS=100000``
267-
268-
Authentication
269-
~~~~~~~~~~~~~~
270-
271-
.. list-table::
272-
:header-rows: 1
273-
:widths: 30 70
274-
275-
* - Connection Option
276-
- Description
277-
278-
* - ``authMechanism``
279-
- | The mechanism {+driver-short+} uses to authenticate the application. Valid
280-
| options are defined in `MECHANISMS. <{+api-root+}pymongo/database.html#pymongo.auth.MECHANISMS>`__
281-
|
282-
| **Data Type**: {+string-data-type+}
283-
| **Default**: ``"SCRAM-SHA-256"`` when connecting to MongoDB v4.0 or later.
284-
| ``"SCRAM-SHA-1"`` when connecting to MongoDB v3.0 through v3.13.
285-
| **MongoClient Example**: ``authMechanism = "MONGODB-X509"``
286-
| **Connection URI Example**: ``authMechanism=MONGODB-X509``
287-
288-
* - ``authMechanismProperties``
289-
- | Options specific to the authentication mechanism. Not needed for all authentication
290-
| mechanisms.
291-
|
292-
| **Data Type**: {+string-data-type+}
293-
| **Default**: ``""``
294-
| **MongoClient Example**: ``authMechanismProperties = "AWS_SESSION_TOKEN:12345"``
295-
| **Connection URI Example**: ``authMechanismProperties=AWS_SESSION_TOKEN:12435``
296-
297-
* - ``authSource``
298-
- | The database to authenticate against.
299-
|
300-
| **Data Type**: {+string-data-type+}
301-
| **Default**: The database in the connection URI, or ``"admin"`` if none is provided
302-
| **MongoClient Example**: ``authSource = "admin"``
303-
| **Connection URI Example**: ``authSource=admin``
304-
305-
* - ``username``
306-
- | The username for authentication. When this option is included in a connection
307-
| URI, you must percent-escape it.
308-
|
309-
| **Data Type**: {+string-data-type+}
310-
| **Default**: ``""``
311-
| **MongoClient Example**: ``username = "my user"``
312-
| **Connection URI Example**: ``username=my+user``
313-
314-
* - ``password``
315-
- | The password for authentication. When this option is included in a connection
316-
| URI, you must percent-escape it.
317-
|
318-
| **Data Type**: {+string-data-type+}
319-
| **Default**: ``""``
320-
| **MongoClient Example**: ``password = "strong password"``
321-
| **Connection URI Example**: ``password=strong+password``
322-
323-
For more information about the connection options in this section, see :ref:`pymongo-auth`.
324-
325-
Read and Write Operations
326-
~~~~~~~~~~~~~~~~~~~~~~~~~
327-
328-
.. list-table::
329-
:header-rows: 1
330-
:widths: 30 70
331-
332-
* - Connection Option
333-
- Description
334-
335-
* - ``replicaSet``
336-
- | Specifies the name of the replica set to connect to.
337-
|
338-
| **Data Type**: {+string-data-type+}
339-
| **Default**: ``null``
340-
| **MongoClient Example**: ``replicaSet='replicaSetName'``
341-
| **Connection URI Example**: ``replicaSet=replicaSetName``
342-
343-
* - ``directConnection``
344-
- | Whether to connect only to the primary member of the replica set.
345-
|
346-
| **Data Type**: {+bool-data-type+}
347-
| **Default**: ``False``
348-
| **MongoClient Example**: ``directConnection=True``
349-
| **Connection URI Example**: ``directConnection=true``
350-
351-
* - ``readPreference``
352-
- | Specifies the client's read-preference settings.
353-
|
354-
| **Data Type**: `read_preferences <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences>`__
355-
| **Default**: ``ReadPreference.Primary``
356-
| **MongoClient Example**: ``readPreference=ReadPreference.SECONDARY_PREFERRED``
357-
| **Connection URI Example**: ``readPreference=secondaryPreferred``
358-
359-
* - ``readConcern``
360-
- | Specifies the client's read-concern settings. For more information, see :manual:`</reference/read-concern/>`.
361-
|
362-
| **Data Type**: {+string-data-type+}
363-
| **Default**: ``None``
364-
| **MongoClient Example**: ``readConcern="majority"``
365-
| **Connection URI Example**: ``readConcern=majority``
366-
367-
* - ``writeConcern``
368-
- | Specifies the client's write-concern settings. For more information, see
369-
:manual:`</reference/write-concern/>`.
370-
|
371-
| **Data Type**: {+string-data-type+}
372-
| **Default**: ``None``
373-
| **MongoClient Example**: ``writeConcern="majority"``
374-
| **Connection URI Example**: ``writeConcern=majority``
375-
376-
* - ``localThresholdMS``
377-
- | The latency window for a replica-set members eligibility. If a member's
378-
round trip ping takes longer than the fastest server's round-trip ping
379-
time plus this value, the server isn't eligible for selection.
380-
|
381-
| **Data Type**: `read_preferences <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences>`__
382-
| **Default**: {+int-data-type+}
383-
| **MongoClient Example**: ``localThresholdMS=35``
384-
| **Connection URI Example**: ``localThresholdMS=35``
385-
386-
* - ``retryReads``
387-
- | Specifies whether the client retries supported read operations. For more
388-
information, see :manual:`Retryable Reads </core/retryable-reads/>` in the {+mdb-server+}
389-
manual.
390-
|
391-
| **Data Type**: {+bool-data-type+}
392-
| **Default**: ``True``
393-
| **MongoClient Example**: ``retryReads=False``
394-
| **Connection URI Example**: ``retryReads=false``
395-
396-
* - ``retryWrites``
397-
- | Specifies whether the client retries supported write operations. For more
398-
information, see :manual:`Retryable Writes </core/retryable-writes/>` in the {+mdb-server+}
399-
manual.
400-
|
401-
| **Data Type**: {+bool-data-type+}
402-
| **Default**: ``True``
403-
| **MongoClient Example**: ``retryWrites=False``
404-
| **Connection URI Example**: ``retryWrites=false``
405-
406-
For more information about the connection options in this section, see
407-
:ref:`pymongo-configure-crud`.
91+
- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__

0 commit comments

Comments
 (0)