1MONGOC_URI_T(3) libmongoc MONGOC_URI_T(3)
2
6 typedef struct _mongoc_uri_t mongoc_uri_t;
7
9 mongoc_uri_t provides an abstraction on top of the MongoDB connection
10 URI format. It provides standardized parsing as well as convenience
11 methods for extracting useful information such as replica hosts or au‐
12 thorization information.
13 See Connection String URI Reference on the MongoDB website for more in‐
15 formation.
16
18 mongodb[+srv]:// <1>
19 [username:password@] <2>
20 host1 <3>
21 [:port1] <4>
22 [,host2[:port2],...[,hostN[:portN]]] <5>
23 [/[database] <6>
24 [?options]] <7>
25 1. "mongodb" is the specifier of the MongoDB protocol. Use "mon‐
27 godb+srv" with a single service name in place of "host1" to specify
28 the initial list of servers with an SRV record.
29 2. An optional username and password.
31 3. The only required part of the uri. This specifies either a host‐
33 name, IPv4 address, IPv6 address enclosed in "[" and "]", or UNIX
34 domain socket.
35 4. An optional port number. Defaults to :27017.
37 5. Extra optional hosts and ports. You would specify multiple hosts,
39 for example, for connections to replica sets.
40 6. The name of the database to authenticate if the connection string
42 includes authentication credentials. If /database is not specified
43 and the connection string includes credentials, defaults to the 'ad‐
44 min' database.
45 7. Connection specific options.
47 NOTE:
49 Option names are case-insensitive. Do not repeat the same option
50 (e.g. "mongodb://localhost/db?opt=value1&OPT=value2") since this may
51 have unexpected results.
52 The MongoDB C Driver exposes constants for each supported connection
54 option. These constants make it easier to discover connection options,
55 but their string values can be used as well.
56 For example, the following calls are equal.
58 uri = mongoc_uri_new ("mongodb://localhost/?" MONGOC_URI_APPNAME "=applicationName");
60 uri = mongoc_uri_new ("mongodb://localhost/?appname=applicationName");
61 uri = mongoc_uri_new ("mongodb://localhost/?appName=applicationName");
62
64 To describe a connection to a replica set named 'test' with the follow‐
65 ing mongod hosts:
66 • db1.example.com on port 27017
68 • db2.example.com on port 2500
70 You would use a connection string that resembles the following.
72 mongodb://db1.example.com,db2.example.com:2500/?replicaSet=test
74
76 If you have configured an SRV record with a name like "_mon‐
77 godb._tcp.server.example.com" whose records are a list of one or more
78 MongoDB server hostnames, use a connection string like this:
79 uri = mongoc_uri_new ("mongodb+srv://server.example.com/?replicaSet=rs&appName=applicationName");
81 The driver prefixes the service name with "_mongodb._tcp.", then per‐
83 forms a DNS SRV query to resolve the service name to one or more host‐
84 names. If this query succeeds, the driver performs a DNS TXT query on
85 the service name (without the "_mongodb._tcp" prefix) for additional
86 URI options configured as TXT records.
87 On Unix, the MongoDB C Driver relies on libresolv to look up SRV and
89 TXT records. If libresolv is unavailable, then using a "mongodb+srv"
90 URI will cause an error. If your libresolv lacks res_nsearch then the
91 driver will fall back to res_search, which is not thread-safe.
92
94 If connecting to a hostname that has both IPv4 and IPv6 DNS records,
95 the behavior follows RFC-6555. A connection to the IPv6 address is at‐
96 tempted first. If IPv6 fails, then a connection is attempted to the
97 IPv4 address. If the connection attempt to IPv6 does not complete
98 within 250ms, then IPv4 is tried in parallel. Whichever succeeds con‐
99 nection first cancels the other. The successful DNS result is cached
100 for 10 minutes.
101 As a consequence, attempts to connect to a mongod only listening on
103 IPv4 may be delayed if there are both A (IPv4) and AAAA (IPv6) DNS
104 records associated with the host.
105 To avoid a delay, configure hostnames to match the MongoDB configura‐
107 tion. That is, only create an A record if the mongod is only listening
108 on IPv4.
109
111┌───────────────────┬──────────────────┬──────────────────┬─────────────────────────────────────┐
112│Constant │ Key │ Default │ Description │
113├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
114│MON‐ │ retryreads │ true │ If "true" and │
115│GOC_URI_RETRYREADS │ │ │ the server is a │
116│ │ │ │ MongoDB 3.6+ │
117│ │ │ │ standalone, │
118│ │ │ │ replica set, or │
119│ │ │ │ sharded cluster, │
120│ │ │ │ the driver │
121│ │ │ │ safely retries a │
122│ │ │ │ read that failed │
123│ │ │ │ due to a network │
124│ │ │ │ error or replica │
125│ │ │ │ set failover. │
126└───────────────────┴──────────────────┴──────────────────┴─────────────────────────────────────┘
127│MONGOC_URI_RETRY‐ │ retrywrites │ true if driver │ If "true" and │
134│WRITES │ │ built w/ TLS │ the server is a │
135│ │ │ │ MongoDB 3.6+ │
136│ │ │ │ replica set or │
137│ │ │ │ sharded cluster, │
138│ │ │ │ the driver │
139│ │ │ │ safely retries a │
140│ │ │ │ write that │
141│ │ │ │ failed due to a │
142│ │ │ │ network error or │
143│ │ │ │ replica set │
144│ │ │ │ failover. Only │
145│ │ │ │ inserts, updates │
146│ │ │ │ of single docu‐ │
147│ │ │ │ ments, or │
148│ │ │ │ deletes of sin‐ │
149│ │ │ │ gle documents │
150│ │ │ │ are retried. │
151├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
152│MONGOC_URI_APPNAME │ appname │ Empty (no app‐ │ The client ap‐ │
153│ │ │ name) │ plication name. │
154│ │ │ │ This value is │
155│ │ │ │ used by MongoDB │
156│ │ │ │ when it logs │
157│ │ │ │ connection in‐ │
158│ │ │ │ formation and │
159│ │ │ │ profile informa‐ │
160│ │ │ │ tion, such as │
161│ │ │ │ slow queries. │
162├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
163│MONGOC_URI_TLS │ tls │ Empty (not set, │ {true|false}, │
164│ │ │ same as false) │ indicating if │
165│ │ │ │ TLS must be │
166│ │ │ │ used. (See also │
167│ │ │ │ mongoc_client_set_ssl_opts() │
168│ │ │ │ and │
169│ │ │ │ mongoc_client_pool_set_ssl_opts().) │
170├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
171│MONGOC_URI_COM‐ │ compressors │ Empty (no com‐ │ Comma separated list of compres‐ │
172│PRESSORS │ │ pressors) │ sors, if any, to use to compress │
173│ │ │ │ the wire protocol messages. Snappy, │
174│ │ │ │ zlib, and zstd are optional build │
175│ │ │ │ time dependencies, and enable the │
176│ │ │ │ "snappy", "zlib", and "zstd" values │
177│ │ │ │ respectively. │
178├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
179│MONGOC_URI_CON‐ │ connecttimeoutms │ 10,000 ms (10 │ This setting applies to new server │
180│NECTTIMEOUTMS │ │ seconds) │ connections. It is also used as the │
181│ │ │ │ socket timeout for server discovery │
182│ │ │ │ and monitoring operations. │
183├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
184│MONGOC_URI_SOCKET‐ │ sockettimeoutms │ 300,000 ms (5 │ The time in milliseconds to attempt │
185│TIMEOUTMS │ │ minutes) │ to send or receive on a socket be‐ │
186│ │ │ │ fore the attempt times out. │
187├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
188│MONGOC_URI_REPLI‐ │ replicaset │ Empty (no repli‐ │ The name of the Replica Set that │
189│CASET │ │ caset) │ the driver should connect to. │
190├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
191│MONGOC_URI_ZLIB‐ │ zlibcompression‐ │ -1 │ When the MONGOC_URI_COMPRESSORS in‐ │
192│COMPRESSIONLEVEL │ level │ │ cludes "zlib" this options config‐ │
193│ │ │ │ ures the zlib compression level, │
194│ │ │ │ when the zlib compressor is used to │
195│ │ │ │ compress client data. │
196└───────────────────┴──────────────────┴──────────────────┴─────────────────────────────────────┘
197│MONGOC_URI_LOAD‐ │ loadbalanced │ false │ If true, this indicates the driver │
200│BALANCED │ │ │ is connecting to a MongoDB cluster │
201│ │ │ │ behind a load balancer. │
202├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
203│MONGOC_URI_SRVMAX‐ │ srvmaxhosts │ 0 │ If zero, the number of hosts in DNS │
204│HOSTS │ │ │ results is unlimited. If greater │
205│ │ │ │ than zero, the number of hosts in │
206│ │ │ │ DNS results is limited to being │
207│ │ │ │ less than or equal to the given │
208│ │ │ │ value. │
209└───────────────────┴──────────────────┴──────────────────┴─────────────────────────────────────┘
210 Setting any of the *timeoutMS options above to 0 will be interpreted as
212 "use the default value".
213
215 ┌────────────────────┬────────────────────┬─────────────────────┐
216 │Constant │ Key │ Description │
217 ├────────────────────┼────────────────────┼─────────────────────┤
218 │MONGOC_URI_AUTH‐ │ authmechanism │ Specifies the mech‐ │
219 │MECHANISM │ │ anism to use when │
220 │ │ │ authenticating as │
221 │ │ │ the provided user. │
222 │ │ │ See Authentication │
223 │ │ │ for supported val‐ │
224 │ │ │ ues. │
225 ├────────────────────┼────────────────────┼─────────────────────┤
226 │MONGOC_URI_AUTH‐ │ authmechanismprop‐ │ Certain authentica‐ │
227 │MECHANISMPROPERTIES │ erties │ tion mechanisms │
228 │ │ │ have additional op‐ │
229 │ │ │ tions that can be │
230 │ │ │ configured. These │
231 │ │ │ options should be │
232 │ │ │ provided as comma │
233 │ │ │ separated op‐ │
234 │ │ │ tion_key:op‐ │
235 │ │ │ tion_value pair and │
236 │ │ │ provided as auth‐ │
237 │ │ │ MechanismProper‐ │
238 │ │ │ ties. Specifying │
239 │ │ │ the same option_key │
240 │ │ │ multiple times has │
241 │ │ │ undefined behavior. │
242 ├────────────────────┼────────────────────┼─────────────────────┤
243 │MONGOC_URI_AUTH‐ │ authsource │ The authSource de‐ │
244 │SOURCE │ │ fines the database │
245 │ │ │ that should be used │
246 │ │ │ to authenticate to. │
247 │ │ │ It is unnecessary │
248 │ │ │ to provide this op‐ │
249 │ │ │ tion the database │
250 │ │ │ name is the same as │
251 │ │ │ the database used │
252 │ │ │ in the URI. │
253 └────────────────────┴────────────────────┴─────────────────────┘
254 Mechanism Properties
256 ┌────────────────────┬───────────────────┬─────────────────────┐
257 │Constant │ Key │ Description │
258 └────────────────────┴───────────────────┴─────────────────────┘
259 │MONGOC_URI_CANONI‐ │ canonicalizehost‐ │ Use the canonical │
266 │CALIZEHOSTNAME │ name │ hostname of the │
267 │ │ │ service, rather │
268 │ │ │ than its configured │
269 │ │ │ alias, when authen‐ │
270 │ │ │ ticating with │
271 │ │ │ Cyrus-SASL Ker‐ │
272 │ │ │ beros. │
273 ├────────────────────┼───────────────────┼─────────────────────┤
274 │MONGOC_URI_GSSAPIS‐ │ gssapiservicename │ Use alternative │
275 │ERVICENAME │ │ service name. The │
276 │ │ │ default is mongodb. │
277 └────────────────────┴───────────────────┴─────────────────────┘
278
280 ┌────────────────────┬─────────────────────┬─────────────────────┐
281 │Constant │ Key │ Description │
282 ├────────────────────┼─────────────────────┼─────────────────────┤
283 │MONGOC_URI_TLS │ tls │ {true|false}, indi‐ │
284 │ │ │ cating if TLS must │
285 │ │ │ be used. │
286 ├────────────────────┼─────────────────────┼─────────────────────┤
287 │MONGOC_URI_TLSCER‐ │ tlscertificatekey‐ │ Path to PEM format‐ │
288 │TIFICATEKEYFILE │ file │ ted Private Key, │
289 │ │ │ with its Public │
290 │ │ │ Certificate con‐ │
291 │ │ │ catenated at the │
292 │ │ │ end. │
293 ├────────────────────┼─────────────────────┼─────────────────────┤
294 │MONGOC_URI_TLSCER‐ │ tlscertificatekey‐ │ The password, if │
295 │TIFICATEKEY‐ │ password │ any, to use to un‐ │
296 │FILEPASSWORD │ │ lock encrypted Pri‐ │
297 │ │ │ vate Key. │
298 ├────────────────────┼─────────────────────┼─────────────────────┤
299 │MON‐ │ tlscafile │ One, or a bundle │
300 │GOC_URI_TLSCAFILE │ │ of, Certificate Au‐ │
301 │ │ │ thorities whom │
302 │ │ │ should be consid‐ │
303 │ │ │ ered to be trusted. │
304 ├────────────────────┼─────────────────────┼─────────────────────┤
305 │MONGOC_URI_TLSAL‐ │ tlsallowinvalidcer‐ │ Accept and ignore │
306 │LOWINVALIDCERTIFI‐ │ tificates │ certificate verifi‐ │
307 │CATES │ │ cation errors (e.g. │
308 │ │ │ untrusted issuer, │
309 │ │ │ expired, etc.) │
310 ├────────────────────┼─────────────────────┼─────────────────────┤
311 │MONGOC_URI_TLSAL‐ │ tlsallowinvalid‐ │ Ignore hostname │
312 │LOWINVALIDHOSTNAMES │ hostnames │ verification of the │
313 │ │ │ certificate (e.g. │
314 │ │ │ Man In The Middle, │
315 │ │ │ using valid cer‐ │
316 │ │ │ tificate, but is‐ │
317 │ │ │ sued for another │
318 │ │ │ hostname) │
319 └────────────────────┴─────────────────────┴─────────────────────┘
320 │MONGOC_URI_TLSINSE‐ │ tlsinsecure │ {true|false}, indi‐ │
332 │CURE │ │ cating if insecure │
333 │ │ │ TLS options should │
334 │ │ │ be used. Currently │
335 │ │ │ this implies MON‐ │
336 │ │ │ GOC_URI_TLSALLOWIN‐ │
337 │ │ │ VALIDCERTIFICATES │
338 │ │ │ and MONGOC_URI_TL‐ │
339 │ │ │ SALLOWINVALIDHOST‐ │
340 │ │ │ NAMES. │
341 ├────────────────────┼─────────────────────┼─────────────────────┤
342 │MONGOC_URI_TLSDIS‐ │ tlsdisablecertifi‐ │ {true|false}, indi‐ │
343 │ABLECERTIFICATERE‐ │ caterevocationcheck │ cates if revocation │
344 │VOCATIONCHECK │ │ checking (CRL / │
345 │ │ │ OCSP) should be │
346 │ │ │ disabled. │
347 ├────────────────────┼─────────────────────┼─────────────────────┤
348 │MONGOC_URI_TLSDIS‐ │ tlsdisableocspend‐ │ {true|false}, indi‐ │
349 │ABLEOCSPEND‐ │ pointcheck │ cates if OCSP re‐ │
350 │POINTCHECK │ │ sponder endpoints │
351 │ │ │ should not be re‐ │
352 │ │ │ quested when an │
353 │ │ │ OCSP response is │
354 │ │ │ not stapled. │
355 └────────────────────┴─────────────────────┴─────────────────────┘
356 See Configuring TLS for details about these options and about building
358 libmongoc with TLS support.
359
361 The following options have been deprecated and may be removed from fu‐
362 ture releases of libmongoc.
363 ┌──────────────────────┬──────────────────┬───────────────────┬──────────────────┐
365 │Constant │ Key │ Deprecated For │ Key │
366 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
367 │MONGOC_URI_SSL │ ssl │ MONGOC_URI_TLS │ tls │
368 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
369 │MON‐ │ sslclientcer‐ │ MON‐ │ tlscertifi‐ │
370 │GOC_URI_SSLCLIENTCER‐ │ tificatekeyfile │ GOC_URI_TLSCER‐ │ catekeyfile │
371 │TIFICATEKEYFILE │ │ TIFICATEKEYFILE │ │
372 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
373 │MON‐ │ sslclientcer‐ │ MON‐ │ tlscertifi‐ │
374 │GOC_URI_SSLCLIENTCER‐ │ tificatekeypass‐ │ GOC_URI_TLSCER‐ │ catekeypassword │
375 │TIFICATEKEYPASSWORD │ word │ TIFICATEKEY‐ │ │
376 │ │ │ FILEPASSWORD │ │
377 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
378 │MONGOC_URI_SSLCER‐ │ sslcertifi‐ │ MON‐ │ tlscafile │
379 │TIFICATEAUTHORITYFILE │ cateauthority‐ │ GOC_URI_TLSCAFILE │ │
380 │ │ file │ │ │
381 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
382 │MONGOC_URI_SSLALLOW‐ │ sslallowinvalid‐ │ MONGOC_URI_TLSAL‐ │ tlsallowinvalid‐ │
383 │INVALIDCERTIFICATES │ certificates │ LOWINVALIDCER‐ │ certificates │
384 │ │ │ TIFICATES │ │
385 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
386 │MONGOC_URI_SSLALLOW‐ │ sslallowinvalid‐ │ MONGOC_URI_TLSAL‐ │ tlsallowinvalid‐ │
387 │INVALIDHOSTNAMES │ hostnames │ LOWINVALIDHOST‐ │ hostnames │
388 │ │ │ NAMES │ │
389 └──────────────────────┴──────────────────┴───────────────────┴──────────────────┘
390
392 Clients in a mongoc_client_pool_t share a topology scanner that runs on
393 a background thread. The thread wakes every heartbeatFrequencyMS (de‐
394 fault 10 seconds) to scan all MongoDB servers in parallel. Whenever an
395 application operation requires a server that is not known--for example,
396 if there is no known primary and your application attempts an in‐
397 sert--the thread rescans all servers every half-second. In this situa‐
398 tion the pooled client waits up to serverSelectionTimeoutMS (default 30
399 seconds) for the thread to find a server suitable for the operation,
400 then returns an error with domain MONGOC_ERROR_SERVER_SELECTION.
401 Technically, the total time an operation may wait while a pooled client
403 scans the topology is controlled both by serverSelectionTimeoutMS and
404 connectTimeoutMS. The longest wait occurs if the last scan begins just
405 at the end of the selection timeout, and a slow or down server requires
406 the full connection timeout before the client gives up.
407 A non-pooled client is single-threaded. Every heartbeatFrequencyMS, it
409 blocks the next application operation while it does a parallel scan.
410 This scan takes as long as needed to check the slowest server: roughly
411 connectTimeoutMS. Therefore the default heartbeatFrequencyMS for sin‐
412 gle-threaded clients is greater than for pooled clients: 60 seconds.
413 By default, single-threaded (non-pooled) clients scan only once when an
415 operation requires a server that is not known. If you attempt an insert
416 and there is no known primary, the client checks all servers once try‐
417 ing to find it, then succeeds or returns an error with domain MON‐
418 GOC_ERROR_SERVER_SELECTION. But if you set serverSelectionTryOnce to
419 "false", the single-threaded client loops, checking all servers every
420 half-second, until serverSelectionTimeoutMS.
421 The total time an operation may wait for a single-threaded client to
423 scan the topology is determined by connectTimeoutMS in the try-once
424 case, or serverSelectionTimeoutMS and connectTimeoutMS if serverSelec‐
425 tionTryOnce is set "false".
426 ┌────────────────────┬─────────────────────┬─────────────────────┐
428 │Constant │ Key │ Description │
429 ├────────────────────┼─────────────────────┼─────────────────────┤
430 │MONGOC_URI_HEART‐ │ heartbeatfrequen‐ │ The interval be‐ │
431 │BEATFREQUENCYMS │ cyms │ tween server moni‐ │
432 │ │ │ toring checks. De‐ │
433 │ │ │ faults to 10,000ms │
434 │ │ │ (10 seconds) in │
435 │ │ │ pooled │
436 │ │ │ (multi-threaded) │
437 │ │ │ mode, 60,000ms (60 │
438 │ │ │ seconds) in │
439 │ │ │ non-pooled mode │
440 │ │ │ (single-threaded). │
441 ├────────────────────┼─────────────────────┼─────────────────────┤
442 │MONGOC_URI_SERVERS‐ │ serverselection‐ │ A timeout in mil‐ │
443 │ELECTIONTIMEOUTMS │ timeoutms │ liseconds to block │
444 │ │ │ for server selec‐ │
445 │ │ │ tion before throw‐ │
446 │ │ │ ing an exception. │
447 │ │ │ The default is │
448 │ │ │ 30,0000ms (30 sec‐ │
449 │ │ │ onds). │
450 └────────────────────┴─────────────────────┴─────────────────────┘
451 │MONGOC_URI_SERVERS‐ │ serverselectiontry‐ │ If "true", the │
464 │ELECTIONTRYONCE │ once │ driver scans the │
465 │ │ │ topology exactly │
466 │ │ │ once after server │
467 │ │ │ selection fails, │
468 │ │ │ then either selects │
469 │ │ │ a server or returns │
470 │ │ │ an error. If it is │
471 │ │ │ false, then the │
472 │ │ │ driver repeatedly │
473 │ │ │ searches for a │
474 │ │ │ suitable server for │
475 │ │ │ up to serverSelec‐ │
476 │ │ │ tionTimeoutMS mil‐ │
477 │ │ │ liseconds (pausing │
478 │ │ │ a half second be‐ │
479 │ │ │ tween attempts). │
480 │ │ │ The default for │
481 │ │ │ serverSelectionTry‐ │
482 │ │ │ Once is "false" for │
483 │ │ │ pooled clients, │
484 │ │ │ otherwise "true". │
485 │ │ │ Pooled clients ig‐ │
486 │ │ │ nore serverSelec‐ │
487 │ │ │ tionTryOnce; they │
488 │ │ │ signal the thread │
489 │ │ │ to rescan the │
490 │ │ │ topology every │
491 │ │ │ half-second until │
492 │ │ │ serverSelection‐ │
493 │ │ │ TimeoutMS expires. │
494 ├────────────────────┼─────────────────────┼─────────────────────┤
495 │MONGOC_URI_SOCK‐ │ socketcheckinter‐ │ Only applies to │
496 │ETCHECKINTERVALMS │ valms │ single threaded │
497 │ │ │ clients. If a │
498 │ │ │ socket has not been │
499 │ │ │ used within this │
500 │ │ │ time, its connec‐ │
501 │ │ │ tion is checked │
502 │ │ │ with a quick │
503 │ │ │ "hello" call before │
504 │ │ │ it is used again. │
505 │ │ │ Defaults to 5,000ms │
506 │ │ │ (5 seconds). │
507 ├────────────────────┼─────────────────────┼─────────────────────┤
508 │MONGOC_URI_DIRECT‐ │ directconnection │ If "true", the │
509 │CONNECTION │ │ driver connects to │
510 │ │ │ a single server di‐ │
511 │ │ │ rectly and will not │
512 │ │ │ monitor additional │
513 │ │ │ servers. If │
514 │ │ │ "false", the driver │
515 │ │ │ connects based on │
516 │ │ │ the presence and │
517 │ │ │ value of the repli‐ │
518 │ │ │ caSet option. │
519 └────────────────────┴─────────────────────┴─────────────────────┘
520 Setting any of the *TimeoutMS options above to 0 will be interpreted as
522 "use the default value".
523
525 These options govern the behavior of a mongoc_client_pool_t. They are
526 ignored by a non-pooled mongoc_client_t.
527 ┌────────────────────┬────────────────────┬──────────────────────────┐
530 │Constant │ Key │ Description │
531 ├────────────────────┼────────────────────┼──────────────────────────┤
532 │MONGOC_URI_MAXPOOL‐ │ maxpoolsize │ The maximum number │
533 │SIZE │ │ of clients created │
534 │ │ │ by a │
535 │ │ │ mongoc_client_pool_t │
536 │ │ │ total (both in the │
537 │ │ │ pool and checked │
538 │ │ │ out). The default │
539 │ │ │ value is 100. Once │
540 │ │ │ it is reached, │
541 │ │ │ mongoc_client_pool_pop() │
542 │ │ │ blocks until an‐ │
543 │ │ │ other thread pushes │
544 │ │ │ a client. │
545 ├────────────────────┼────────────────────┼──────────────────────────┤
546 │MONGOC_URI_MINPOOL‐ │ minpoolsize │ Deprecated. This op‐ │
547 │SIZE │ │ tion's behavior does not │
548 │ │ │ match its name, and its │
549 │ │ │ actual behavior will │
550 │ │ │ likely hurt performance. │
551 ├────────────────────┼────────────────────┼──────────────────────────┤
552 │MONGOC_URI_MAXIDLE‐ │ maxidletimems │ Not implemented. │
553 │TIMEMS │ │ │
554 ├────────────────────┼────────────────────┼──────────────────────────┤
555 │MONGOC_URI_WAIT‐ │ waitqueuemultiple │ Not implemented. │
556 │QUEUEMULTIPLE │ │ │
557 ├────────────────────┼────────────────────┼──────────────────────────┤
558 │MONGOC_URI_WAIT‐ │ waitqueuetimeoutms │ The maximum time to wait │
559 │QUEUETIMEOUTMS │ │ for a client to become │
560 │ │ │ available from the pool. │
561 └────────────────────┴────────────────────┴──────────────────────────┘
562
564 ┌───────────────────┬────────────┬─────────────────────┐
565 │Constant │ Key │ Description │
566 └───────────────────┴────────────┴─────────────────────┘
567 MONGOC_URI_W w Determines the
596 write concern
597 (guarantee). Valid
598 values:
599 • 0 = The
601 driver
602 will not
603 acknowl‐
604 edge write
605 operations
606 but will
607 pass or
608 handle any
609 network
610 and socket
611 errors
612 that it
613 receives
614 to the
615 client. If
616 you dis‐
617 able write
618 concern
619 but enable
620 the get‐
621 LastError
622 command’s
623 w option,
624 w over‐
625 rides the
626 w option.
627 • 1 = Pro‐
629 vides ba‐
630 sic ac‐
631 knowledge‐
632 ment of
633 write op‐
634 erations.
635 By speci‐
636 fying 1,
637 you re‐
638 quire that
639 a stand‐
640 alone mon‐
641 god in‐
642 stance, or
643 the pri‐
644 mary for
645 replica
646 sets, ac‐
647 knowledge
648 all write
649 opera‐
650 tions. For
651 drivers
652 released
653 after the
654 default
655 write con‐
656 cern
657 change,
658 this is
659 the de‐
660 fault
661 write con‐
662 cern set‐
663 ting.
664 • majority =
666 For
667 replica
668 sets, if
669 you spec‐
670 ify the
671 special
672 majority
673 value to w
674 option,
675 write op‐
676 erations
677 will only
678 return
679 success‐
680 fully af‐
681 ter a ma‐
682 jority of
683 the con‐
684 figured
685 replica
686 set mem‐
687 bers have
688 acknowl‐
689 edged the
690 write op‐
691 eration.
692 • n = For
694 replica
695 sets, if
696 you spec‐
697 ify a num‐
698 ber n
699 greater
700 than 1,
701 operations
702 with this
703 write con‐
704 cern re‐
705 turn only
706 after n
707 members of
708 the set
709 have ac‐
710 knowledged
711 the write.
712 If you set
713 n to a
714 number
715 that is
716 greater
717 than the
718 number of
719 available
720 set mem‐
721 bers or
722 members
723 that hold
724 data, Mon‐
725 goDB will
726 wait, po‐
727 tentially
728 indefi‐
729 nitely,
730 for these
731 members to
732 become
733 available.
734 • tags = For
736 replica
737 sets, you
738 can spec‐
739 ify a tag
740 set to re‐
741 quire that
742 all mem‐
743 bers of
744 the set
745 that have
746 these tags
747 configured
748 return
749 confirma‐
750 tion of
751 the write
752 operation.
753 ├───────────────────┼────────────┼─────────────────────┤
754 │MONGOC_URI_WTIME‐ │ wtimeoutms │ The time in mil‐ │
755 │OUTMS │ │ liseconds to wait │
756 │ │ │ for replication to │
757 │ │ │ succeed, as speci‐ │
758 │ │ │ fied in the w op‐ │
759 │ │ │ tion, before timing │
760 │ │ │ out. When wtime‐ │
761 │ │ │ outMS is 0, write │
762 │ │ │ operations will │
763 │ │ │ never time out. │
764 ├───────────────────┼────────────┼─────────────────────┤
765 │MONGOC_URI_JOURNAL │ journal │ Controls whether │
766 │ │ │ write operations │
767 │ │ │ will wait until the │
768 │ │ │ mongod acknowledges │
769 │ │ │ the write opera‐ │
770 │ │ │ tions and commits │
771 │ │ │ the data to the on │
772 │ │ │ disk journal. │
773 │ │ │ │
774 │ │ │ • true = │
775 │ │ │ Enables │
776 │ │ │ journal │
777 │ │ │ commit ac‐ │
778 │ │ │ knowledge‐ │
779 │ │ │ ment write │
780 │ │ │ concern. │
781 │ │ │ Equivalent │
782 │ │ │ to speci‐ │
783 │ │ │ fying the │
784 │ │ │ getLastEr‐ │
785 │ │ │ ror com‐ │
786 │ │ │ mand with │
787 │ │ │ the j op‐ │
788 │ │ │ tion en‐ │
789 │ │ │ abled. │
790 │ │ │ │
791 │ │ │ • false = │
792 │ │ │ Does not │
793 │ │ │ require │
794 │ │ │ that mon‐ │
795 │ │ │ god commit │
796 │ │ │ write op‐ │
797 │ │ │ erations │
798 │ │ │ to the │
799 │ │ │ journal │
800 │ │ │ before ac‐ │
801 │ │ │ knowledg‐ │
802 │ │ │ ing the │
803 │ │ │ write op‐ │
804 │ │ │ eration. │
805 │ │ │ This is │
806 │ │ │ the de‐ │
807 │ │ │ fault op‐ │
808 │ │ │ tion for │
809 │ │ │ the jour‐ │
810 │ │ │ nal param‐ │
811 │ │ │ eter. │
812 └───────────────────┴────────────┴─────────────────────┘
813
815 ┌────────────────────┬──────────────────┬─────────────────────┐
816 │Constant │ Key │ Description │
817 └────────────────────┴──────────────────┴─────────────────────┘
818 │MONGOC_URI_READCON‐ │ readconcernlevel │ The level of isola‐ │
820 │CERNLEVEL │ │ tion for read oper‐ │
821 │ │ │ ations. If the │
822 │ │ │ level is left un‐ │
823 │ │ │ specified, the │
824 │ │ │ server default will │
825 │ │ │ be used. See │
826 │ │ │ readConcern in the │
827 │ │ │ MongoDB Manual for │
828 │ │ │ details. │
829 └────────────────────┴──────────────────┴─────────────────────┘
830
832 When connected to a replica set, the driver chooses which member to
833 query using the read preference:
834 1. Choose members whose type matches "readPreference".
836 2. From these, if there are any tags sets configured, choose members
838 matching the first tag set. If there are none, fall back to the next
839 tag set and so on, until some members are chosen or the tag sets are
840 exhausted.
841 3. From the chosen servers, distribute queries randomly among the
843 server with the fastest round-trip times. These include the server
844 with the fastest time and any whose round-trip time is no more than
845 "localThresholdMS" slower.
846 ┌────────────────────┬─────────────────────┬─────────────────────┐
848 │Constant │ Key │ Description │
849 ├────────────────────┼─────────────────────┼─────────────────────┤
850 │MONGOC_URI_READ‐ │ readpreference │ Specifies the │
851 │PREFERENCE │ │ replica set read │
852 │ │ │ preference for this │
853 │ │ │ connection. This │
854 │ │ │ setting overrides │
855 │ │ │ any secondaryOk │
856 │ │ │ value. The read │
857 │ │ │ preference values │
858 │ │ │ are the following: │
859 │ │ │ │
860 │ │ │ • primary │
861 │ │ │ (default) │
862 │ │ │ │
863 │ │ │ • prima‐ │
864 │ │ │ ryPre‐ │
865 │ │ │ ferred │
866 │ │ │ │
867 │ │ │ • secondary │
868 │ │ │ │
869 │ │ │ • sec‐ │
870 │ │ │ ondaryPre‐ │
871 │ │ │ ferred │
872 │ │ │ │
873 │ │ │ • nearest │
874 ├────────────────────┼─────────────────────┼─────────────────────┤
875 │MONGOC_URI_READ‐ │ readpreferencetags │ A representation of │
876 │PREFERENCETAGS │ │ a tag set. See also │
877 │ │ │ Tag Sets. │
878 └────────────────────┴─────────────────────┴─────────────────────┘
879 │MONGOC_URI_LO‐ │ localthresholdms │ How far to distrib‐ │
886 │CALTHRESHOLDMS │ │ ute queries, beyond │
887 │ │ │ the server with the │
888 │ │ │ fastest round-trip │
889 │ │ │ time. By default, │
890 │ │ │ only servers within │
891 │ │ │ 15ms of the fastest │
892 │ │ │ round-trip time re‐ │
893 │ │ │ ceive queries. │
894 ├────────────────────┼─────────────────────┼─────────────────────┤
895 │MONGOC_URI_MAXSTAL‐ │ maxstalenessseconds │ The maximum repli‐ │
896 │ENESSSECONDS │ │ cation lag, in wall │
897 │ │ │ clock time, that a │
898 │ │ │ secondary can suf‐ │
899 │ │ │ fer and still be │
900 │ │ │ eligible. The │
901 │ │ │ smallest allowed │
902 │ │ │ value for maxStale‐ │
903 │ │ │ nessSeconds is 90 │
904 │ │ │ seconds. │
905 └────────────────────┴─────────────────────┴─────────────────────┘
906 NOTE:
908 When connecting to more than one mongos, libmongoc's localThresh‐
909 oldMS applies only to the selection of mongos servers. The threshold
910 for selecting among replica set members in shards is controlled by
911 the mongos's localThreshold command line option.
912
914 For historical reasons, the following options are available. They
915 should however not be used.
916 ┌────────────────┬──────┬─────────────────────┐
918 │Constant │ Key │ Description │
919 ├────────────────┼──────┼─────────────────────┤
920 │MONGOC_URI_SAFE │ safe │ {true|false} Same │
921 │ │ │ as w={1|0} │
922 └────────────────┴──────┴─────────────────────┘
923
925 MongoDB, Inc
926
928 2017-present, MongoDB, Inc
9291.25.1 Nov 08, 2023 MONGOC_URI_T(3)