1MONGOC_URI_T(3) MongoDB C Driver MONGOC_URI_T(3)
2
6 mongoc_uri_t - mongoc_uri_t
7
9 typedef struct _mongoc_uri_t mongoc_uri_t;
10
12 mongoc_uri_t provides an abstraction on top of the MongoDB connection
13 URI format. It provides standardized parsing as well as convenience
14 methods for extracting useful information such as replica hosts or
15 authorization information.
16 See Connection String URI Reference on the MongoDB website for more
18 information.
19
21 mongodb[+srv]:// <1>
22 [username:password@] <2>
23 host1 <3>
24 [:port1] <4>
25 [,host2[:port2],...[,hostN[:portN]]] <5>
26 [/[database] <6>
27 [?options]] <7>
28 1. "mongodb" is the specifier of the MongoDB protocol. Use "mon‐
30 godb+srv" with a single service name in place of "host1" to specify
31 the initial list of servers with an SRV record.
32 2. An optional username and password.
34 3. The only required part of the uri. This specifies either a host‐
36 name, IPv4 address, IPv6 address enclosed in "[" and "]", or UNIX
37 domain socket.
38 4. An optional port number. Defaults to :27017.
40 5. Extra optional hosts and ports. You would specify multiple hosts,
42 for example, for connections to replica sets.
43 6. The name of the database to authenticate if the connection string
45 includes authentication credentials. If /database is not specified
46 and the connection string includes credentials, defaults to the
47 'admin' database.
48 7. Connection specific options.
50 NOTE:
52 Option names are case-insensitive
53 The MongoDB C Driver exposes constants for each supported connection
55 option. These constants make it easier to discover connection options,
56 but their string values can be used as well.
57 For example, the following calls are equal.
59 uri = mongoc_uri_new ("mongodb://localhost/?" MONGOC_URI_APPNAME "=applicationName");
61 uri = mongoc_uri_new ("mongodb://localhost/?appname=applicationName");
62 uri = mongoc_uri_new ("mongodb://localhost/?appName=applicationName");
63
65 To describe a connection to a replica set named 'test' with the follow‐
66 ing mongod hosts:
67 · db1.example.com on port 27017
69 · db2.example.com on port 2500
71 You would use a connection string that resembles the following.
73 mongodb://db1.example.com,db2.example.com:2500/?replicaSet=test
75
77 If you have configured an SRV record with a name like "_mon‐
78 godb._tcp.server.example.com" whose records are a list of one or more
79 MongoDB server hostnames, use a connection string like this:
80 uri = mongoc_uri_new ("mongodb+srv://server.example.com/?replicaSet=rs&appName=applicationName");
82 The driver prefixes the service name with "_mongodb._tcp.", then per‐
84 forms a DNS SRV query to resolve the service name to one or more host‐
85 names. If this query succeeds, the driver performs a DNS TXT query on
86 the service name (without the "_mongodb._tcp" prefix) for additional
87 URI options configured as TXT records.
88 On Unix, the MongoDB C Driver relies on libresolv to look up SRV and
90 TXT records. If libresolv is unavailable, then using a "mongodb+srv"
91 URI will cause an error. If your libresolv lacks res_nsearch then the
92 driver will fall back to res_search, which is not thread-safe.
93
95 If connecting to a hostname that has both IPv4 and IPv6 DNS records,
96 the behavior follows RFC-6555. A connection to the IPv6 address is
97 attempted first. If IPv6 fails, then a connection is attempted to the
98 IPv4 address. If the connection attempt to IPv6 does not complete
99 within 250ms, then IPv4 is tried in parallel. Whichever succeeds con‐
100 nection first cancels the other. The successful DNS result is cached
101 for 10 minutes.
102 As a consequence, attempts to connect to a mongod only listening on
104 IPv4 may be delayed if there are both A (IPv4) and AAAA (IPv6) DNS
105 records associated with the host.
106 To avoid a delay, configure hostnames to match the MongoDB configura‐
108 tion. That is, only create an A record if the mongod is only listening
109 on IPv4.
110
112 ┌────────────────────┬──────────────────┬────────────────────────────────┐
113 │Constant │ Key │ Description │
114 ├────────────────────┼──────────────────┼────────────────────────────────┤
115 │MONGOC_URI_RETRY‐ │ retrywrites │ If "true" and the │
116 │WRITES │ │ server is a MongoDB │
117 │ │ │ 3.6+ replica set or │
118 │ │ │ sharded cluster, │
119 │ │ │ the driver safely │
120 │ │ │ retries a write │
121 │ │ │ that failed due to │
122 │ │ │ a network error or │
123 │ │ │ replica set │
124 │ │ │ failover. Only │
125 │ │ │ inserts, updates of │
126 │ │ │ single documents, │
127 │ │ │ or deletes of sin‐ │
128 │ │ │ gle documents are │
129 │ │ │ retried. │
130 └────────────────────┴──────────────────┴────────────────────────────────┘
131 │MONGOC_URI_APPNAME │ appname │ The client applica‐ │
134 │ │ │ tion name. This │
135 │ │ │ value is used by │
136 │ │ │ MongoDB when it │
137 │ │ │ logs connection │
138 │ │ │ information and │
139 │ │ │ profile informa‐ │
140 │ │ │ tion, such as slow │
141 │ │ │ queries. │
142 ├────────────────────┼──────────────────┼────────────────────────────────┤
143 │MONGOC_URI_SSL │ ssl │ {true|false}, indi‐ │
144 │ │ │ cating if SSL must │
145 │ │ │ be used. (See also │
146 │ │ │ mon‐ │
147 │ │ │ goc_client_set_ssl_opts │
148 │ │ │ and mon‐ │
149 │ │ │ goc_client_pool_set_ssl_opts.) │
150 ├────────────────────┼──────────────────┼────────────────────────────────┤
151 │MONGOC_URI_COMPRES‐ │ compressors │ Comma separated list of com‐ │
152 │SORS │ │ pressors, if any, to use to │
153 │ │ │ compress the wire protocol │
154 │ │ │ messages. Snappy are Zlib are │
155 │ │ │ optional build time dependen‐ │
156 │ │ │ cies, and enable the "snappy" │
157 │ │ │ and "zlib" values respec‐ │
158 │ │ │ tively. Defaults to empty (no │
159 │ │ │ compressors). │
160 ├────────────────────┼──────────────────┼────────────────────────────────┤
161 │MONGOC_URI_CONNECT‐ │ connecttimeoutms │ This setting applies to new │
162 │TIMEOUTMS │ │ server connections. It is also │
163 │ │ │ used as the socket timeout for │
164 │ │ │ server discovery and monitor‐ │
165 │ │ │ ing operations. The default is │
166 │ │ │ 10,000 ms (10 seconds). │
167 ├────────────────────┼──────────────────┼────────────────────────────────┤
168 │MONGOC_URI_SOCKET‐ │ sockettimeoutms │ The time in milliseconds to │
169 │TIMEOUTMS │ │ attempt to send or receive on │
170 │ │ │ a socket before the attempt │
171 │ │ │ times out. The default is │
172 │ │ │ 300,000 (5 minutes). │
173 ├────────────────────┼──────────────────┼────────────────────────────────┤
174 │MONGOC_URI_REPLI‐ │ replicaset │ The name of the Replica Set │
175 │CASET │ │ that the driver should connect │
176 │ │ │ to. │
177 ├────────────────────┼──────────────────┼────────────────────────────────┤
178 │MONGOC_URI_ZLIBCOM‐ │ zlibcompression‐ │ When the MONGOC_URI_COMPRES‐ │
179 │PRESSIONLEVEL │ level │ SORS includes "zlib" this │
180 │ │ │ options configures the zlib │
181 │ │ │ compression level, when the │
182 │ │ │ zlib compressor is used to │
183 │ │ │ compress client data. │
184 └────────────────────┴──────────────────┴────────────────────────────────┘
185 Setting any of the *timeoutMS options above to 0 will be interpreted as
187 "use the default value".
188
190 ┌────────────────────┬────────────────────┬─────────────────────────┐
191 │Constant │ Key │ Description │
192 └────────────────────┴────────────────────┴─────────────────────────┘
193 │MONGOC_URI_AUTH‐ │ authmechanism │ Specifies the mech‐ │
200 │MECHANISM │ │ anism to use when │
201 │ │ │ authenticating as │
202 │ │ │ the provided user. │
203 │ │ │ See Authentication │
204 │ │ │ for supported val‐ │
205 │ │ │ ues. │
206 ├────────────────────┼────────────────────┼─────────────────────────┤
207 │MONGOC_URI_AUTH‐ │ authmechanismprop‐ │ Certain authentica‐ │
208 │MECHANISMPROPERTIES │ erties │ tion mechanisms │
209 │ │ │ have additional │
210 │ │ │ options that can be │
211 │ │ │ configured. These │
212 │ │ │ options should be │
213 │ │ │ provided as comma │
214 │ │ │ separated │
215 │ │ │ option_key:option_value │
216 │ │ │ pair and provided │
217 │ │ │ as authMechanism‐ │
218 │ │ │ Properties. │
219 ├────────────────────┼────────────────────┼─────────────────────────┤
220 │MONGOC_URI_AUTH‐ │ authsource │ The authSource defines │
221 │SOURCE │ │ the database that │
222 │ │ │ should be used to │
223 │ │ │ authenticate to. It is │
224 │ │ │ unnecessary to provide │
225 │ │ │ this option the data‐ │
226 │ │ │ base name is the same │
227 │ │ │ as the database used in │
228 │ │ │ the URI. │
229 └────────────────────┴────────────────────┴─────────────────────────┘
230 Mechanism Properties
232 ┌────────────────────┬───────────────────┬─────────────────────┐
233 │Constant │ Key │ Description │
234 ├────────────────────┼───────────────────┼─────────────────────┤
235 │MONGOC_URI_CANONI‐ │ canonicalizehost‐ │ Use the canonical │
236 │CALIZEHOSTNAME │ name │ hostname of the │
237 │ │ │ service, rather │
238 │ │ │ than its configured │
239 │ │ │ alias, when authen‐ │
240 │ │ │ ticating with │
241 │ │ │ Cyrus-SASL Ker‐ │
242 │ │ │ beros. │
243 ├────────────────────┼───────────────────┼─────────────────────┤
244 │MONGOC_URI_GSSAPIS‐ │ gssapiservicename │ Use alternative │
245 │ERVICENAME │ │ service name. The │
246 │ │ │ default is mongodb. │
247 └────────────────────┴───────────────────┴─────────────────────┘
248
250 ┌──────────────────────┬─────────────────────┬─────────────────────┐
251 │Constant │ Key │ Description │
252 ├──────────────────────┼─────────────────────┼─────────────────────┤
253 │MON‐ │ sslclientcertifi‐ │ Path to PEM format‐ │
254 │GOC_URI_SSLCLIENTCER‐ │ catekeyfile │ ted Private Key, │
255 │TIFICATEKEYFILE │ │ with its Public │
256 │ │ │ Certificate con‐ │
257 │ │ │ catenated at the │
258 │ │ │ end. │
259 └──────────────────────┴─────────────────────┴─────────────────────┘
260 │MON‐ │ sslclientcertifi‐ │ The password, if │
266 │GOC_URI_SSLCLIENTCER‐ │ catekeypassword │ any, to use to │
267 │TIFICATEKEYPASSWORD │ │ unlock encrypted │
268 │ │ │ Private Key. │
269 ├──────────────────────┼─────────────────────┼─────────────────────┤
270 │MONGOC_URI_SSLCER‐ │ sslcertificateau‐ │ One, or a bundle │
271 │TIFICATEAUTHORITYFILE │ thorityfile │ of, Certificate │
272 │ │ │ Authorities whom │
273 │ │ │ should be consid‐ │
274 │ │ │ ered to be trusted. │
275 ├──────────────────────┼─────────────────────┼─────────────────────┤
276 │MONGOC_URI_SSLALLOW‐ │ sslallowinvalidcer‐ │ Accept and ignore │
277 │INVALIDCERTIFICATES │ tificates │ certificate verifi‐ │
278 │ │ │ cation errors (e.g. │
279 │ │ │ untrusted issuer, │
280 │ │ │ expired, etc etc) │
281 ├──────────────────────┼─────────────────────┼─────────────────────┤
282 │MONGOC_URI_SSLALLOW‐ │ sslallowinvalid‐ │ Ignore hostname │
283 │INVALIDHOSTNAMES │ hostnames │ verification of the │
284 │ │ │ certificate (e.g. │
285 │ │ │ Man In The Middle, │
286 │ │ │ using valid cer‐ │
287 │ │ │ tificate, but │
288 │ │ │ issued for another │
289 │ │ │ hostname) │
290 └──────────────────────┴─────────────────────┴─────────────────────┘
291 See mongoc_ssl_opt_t for details about these options and about building
293 libmongoc with SSL support.
294
296 Clients in a mongoc_client_pool_t share a topology scanner that runs on
297 a background thread. The thread wakes every heartbeatFrequencyMS
298 (default 10 seconds) to scan all MongoDB servers in parallel. Whenever
299 an application operation requires a server that is not known--for exam‐
300 ple, if there is no known primary and your application attempts an
301 insert--the thread rescans all servers every half-second. In this situ‐
302 ation the pooled client waits up to serverSelectionTimeoutMS (default
303 30 seconds) for the thread to find a server suitable for the operation,
304 then returns an error with domain MONGOC_ERROR_SERVER_SELECTION.
305 Technically, the total time an operation may wait while a pooled client
307 scans the topology is controlled both by serverSelectionTimeoutMS and
308 connectTimeoutMS. The longest wait occurs if the last scan begins just
309 at the end of the selection timeout, and a slow or down server requires
310 the full connection timeout before the client gives up.
311 A non-pooled client is single-threaded. Every heartbeatFrequencyMS, it
313 blocks the next application operation while it does a parallel scan.
314 This scan takes as long as needed to check the slowest server: roughly
315 connectTimeoutMS. Therefore the default heartbeatFrequencyMS for sin‐
316 gle-threaded clients is greater than for pooled clients: 60 seconds.
317 By default, single-threaded (non-pooled) clients scan only once when an
319 operation requires a server that is not known. If you attempt an insert
320 and there is no known primary, the client checks all servers once try‐
321 ing to find it, then succeeds or returns an error with domain MON‐
322 GOC_ERROR_SERVER_SELECTION. But if you set serverSelectionTryOnce to
323 "false", the single-threaded client loops, checking all servers every
324 half-second, until serverSelectionTimeoutMS.
325 The total time an operation may wait for a single-threaded client to
327 scan the topology is determined by connectTimeoutMS in the try-once
328 case, or serverSelectionTimeoutMS and connectTimeoutMS if serverSelec‐
329 tionTryOnce is set "false".
330 ┌────────────────────┬─────────────────────┬─────────────────────┐
332 │Constant │ Key │ Description │
333 ├────────────────────┼─────────────────────┼─────────────────────┤
334 │MONGOC_URI_HEART‐ │ heartbeatfrequen‐ │ The interval │
335 │BEATFREQUENCYMS │ cyms │ between server mon‐ │
336 │ │ │ itoring checks. │
337 │ │ │ Defaults to │
338 │ │ │ 10,000ms (10 sec‐ │
339 │ │ │ onds) in pooled │
340 │ │ │ (multi-threaded) │
341 │ │ │ mode, 60,000ms (60 │
342 │ │ │ seconds) in │
343 │ │ │ non-pooled mode │
344 │ │ │ (single-threaded). │
345 ├────────────────────┼─────────────────────┼─────────────────────┤
346 │MONGOC_URI_SERVERS‐ │ serverselection‐ │ A timeout in mil‐ │
347 │ELECTIONTIMEOUTMS │ timeoutms │ liseconds to block │
348 │ │ │ for server selec‐ │
349 │ │ │ tion before throw‐ │
350 │ │ │ ing an exception. │
351 │ │ │ The default is │
352 │ │ │ 30,0000ms (30 sec‐ │
353 │ │ │ onds). │
354 ├────────────────────┼─────────────────────┼─────────────────────┤
355 │MONGOC_URI_SERVERS‐ │ serverselectiontry‐ │ If "true", the │
356 │ELECTIONTRYONCE │ once │ driver scans the │
357 │ │ │ topology exactly │
358 │ │ │ once after server │
359 │ │ │ selection fails, │
360 │ │ │ then either selects │
361 │ │ │ a server or returns │
362 │ │ │ an error. If it is │
363 │ │ │ false, then the │
364 │ │ │ driver repeatedly │
365 │ │ │ searches for a │
366 │ │ │ suitable server for │
367 │ │ │ up to serverSelec‐ │
368 │ │ │ tionTimeoutMS mil‐ │
369 │ │ │ liseconds (pausing │
370 │ │ │ a half second │
371 │ │ │ between attempts). │
372 │ │ │ The default for │
373 │ │ │ serverSelectionTry‐ │
374 │ │ │ Once is "false" for │
375 │ │ │ pooled clients, │
376 │ │ │ otherwise "true". │
377 │ │ │ Pooled clients │
378 │ │ │ ignore serverSelec‐ │
379 │ │ │ tionTryOnce; they │
380 │ │ │ signal the thread │
381 │ │ │ to rescan the │
382 │ │ │ topology every │
383 │ │ │ half-second until │
384 │ │ │ serverSelection‐ │
385 │ │ │ TimeoutMS expires. │
386 └────────────────────┴─────────────────────┴─────────────────────┘
387 │MONGOC_URI_SOCK‐ │ socketcheckinter‐ │ Only applies to │
398 │ETCHECKINTERVALMS │ valms │ single threaded │
399 │ │ │ clients. If a │
400 │ │ │ socket has not been │
401 │ │ │ used within this │
402 │ │ │ time, its connec‐ │
403 │ │ │ tion is checked │
404 │ │ │ with a quick │
405 │ │ │ "isMaster" call │
406 │ │ │ before it is used │
407 │ │ │ again. Defaults to │
408 │ │ │ 5,000ms (5 sec‐ │
409 │ │ │ onds). │
410 └────────────────────┴─────────────────────┴─────────────────────┘
411 Setting any of the *TimeoutMS options above to 0 will be interpreted as
413 "use the default value".
414
416 These options govern the behavior of a mongoc_client_pool_t. They are
417 ignored by a non-pooled mongoc_client_t.
418 ┌────────────────────┬────────────────────┬─────────────────────┐
420 │Constant │ Key │ Description │
421 ├────────────────────┼────────────────────┼─────────────────────┤
422 │MONGOC_URI_MAXPOOL‐ │ maxpoolsize │ The maximum number │
423 │SIZE │ │ of clients created │
424 │ │ │ by a mon‐ │
425 │ │ │ goc_client_pool_t │
426 │ │ │ total (both in the │
427 │ │ │ pool and checked │
428 │ │ │ out). The default │
429 │ │ │ value is 100. Once │
430 │ │ │ it is reached, mon‐ │
431 │ │ │ goc_client_pool_pop │
432 │ │ │ blocks until │
433 │ │ │ another thread │
434 │ │ │ pushes a client. │
435 ├────────────────────┼────────────────────┼─────────────────────┤
436 │MONGOC_URI_MINPOOL‐ │ minpoolsize │ Deprecated. This │
437 │SIZE │ │ option's behavior │
438 │ │ │ does not match its │
439 │ │ │ name, and its │
440 │ │ │ actual behavior │
441 │ │ │ will likely hurt │
442 │ │ │ performance. │
443 ├────────────────────┼────────────────────┼─────────────────────┤
444 │MONGOC_URI_MAXIDLE‐ │ maxidletimems │ Not implemented. │
445 │TIMEMS │ │ │
446 ├────────────────────┼────────────────────┼─────────────────────┤
447 │MONGOC_URI_WAIT‐ │ waitqueuemultiple │ Not implemented. │
448 │QUEUEMULTIPLE │ │ │
449 ├────────────────────┼────────────────────┼─────────────────────┤
450 │MONGOC_URI_WAIT‐ │ waitqueuetimeoutms │ Not implemented. │
451 │QUEUETIMEOUTMS │ │ │
452 └────────────────────┴────────────────────┴─────────────────────┘
453
455 ┌───────────────────┬────────────┬─────────────────────┐
456 │Constant │ Key │ Description │
457 └───────────────────┴────────────┴─────────────────────┘
458 MONGOC_URI_W w Determines the
464 write concern
465 (guarantee). Valid
466 values:
467 · 0 = The
469 driver
470 will not
471 acknowl‐
472 edge write
473 operations
474 but will
475 pass or
476 handle any
477 network
478 and socket
479 errors
480 that it
481 receives
482 to the
483 client. If
484 you dis‐
485 able write
486 concern
487 but enable
488 the get‐
489 LastError
490 command’s
491 w option,
492 w over‐
493 rides the
494 w option.
495 · 1 = Pro‐
497 vides
498 basic
499 acknowl‐
500 edgement
501 of write
502 opera‐
503 tions. By
504 specifying
505 1, you
506 require
507 that a
508 standalone
509 mongod
510 instance,
511 or the
512 primary
513 for
514 replica
515 sets,
516 acknowl‐
517 edge all
518 write
519 opera‐
520 tions. For
521 drivers
522 released
523 after the
524 default
525 write con‐
526 cern
527 change,
528 this is
529 the
530 default
531 write con‐
532 cern set‐
533 ting.
534 · majority =
536 For
537 replica
538 sets, if
539 you spec‐
540 ify the
541 special
542 majority
543 value to w
544 option,
545 write
546 operations
547 will only
548 return
549 success‐
550 fully
551 after a
552 majority
553 of the
554 configured
555 replica
556 set mem‐
557 bers have
558 acknowl‐
559 edged the
560 write
561 operation.
562 · n = For
564 replica
565 sets, if
566 you spec‐
567 ify a num‐
568 ber n
569 greater
570 than 1,
571 operations
572 with this
573 write con‐
574 cern
575 return
576 only after
577 n members
578 of the set
579 have
580 acknowl‐
581 edged the
582 write. If
583 you set n
584 to a num‐
585 ber that
586 is greater
587 than the
588 number of
589 available
590 set mem‐
591 bers or
592 members
593 that hold
594 data, Mon‐
595 goDB will
596 wait,
597 poten‐
598 tially
599 indefi‐
600 nitely,
601 for these
602 members to
603 become
604 available.
605 · tags = For
607 replica
608 sets, you
609 can spec‐
610 ify a tag
611 set to
612 require
613 that all
614 members of
615 the set
616 that have
617 these tags
618 configured
619 return
620 confirma‐
621 tion of
622 the write
623 operation.
624 ├───────────────────┼────────────┼─────────────────────┤
625 │MONGOC_URI_WTIME‐ │ wtimeoutms │ The time in mil‐ │
626 │OUTMS │ │ liseconds to wait │
627 │ │ │ for replication to │
628 │ │ │ succeed, as speci‐ │
629 │ │ │ fied in the w │
630 │ │ │ option, before tim‐ │
631 │ │ │ ing out. When │
632 │ │ │ wtimeoutMS is 0, │
633 │ │ │ write operations │
634 │ │ │ will never time │
635 │ │ │ out. │
636 ├───────────────────┼────────────┼─────────────────────┤
637 │MONGOC_URI_JOURNAL │ journal │ Controls whether │
638 │ │ │ write operations │
639 │ │ │ will wait until the │
640 │ │ │ mongod acknowledges │
641 │ │ │ the write opera‐ │
642 │ │ │ tions and commits │
643 │ │ │ the data to the on │
644 │ │ │ disk journal. │
645 │ │ │ │
646 │ │ │ · true = │
647 │ │ │ Enables │
648 │ │ │ journal │
649 │ │ │ commit │
650 │ │ │ acknowl‐ │
651 │ │ │ edgement │
652 │ │ │ write con‐ │
653 │ │ │ cern. │
654 │ │ │ Equivalent │
655 │ │ │ to speci‐ │
656 │ │ │ fying the │
657 │ │ │ getLastEr‐ │
658 │ │ │ ror com‐ │
659 │ │ │ mand with │
660 │ │ │ the j │
661 │ │ │ option │
662 │ │ │ enabled. │
663 │ │ │ │
664 │ │ │ · false = │
665 │ │ │ Does not │
666 │ │ │ require │
667 │ │ │ that mon‐ │
668 │ │ │ god commit │
669 │ │ │ write │
670 │ │ │ operations │
671 │ │ │ to the │
672 │ │ │ journal │
673 │ │ │ before │
674 │ │ │ acknowl‐ │
675 │ │ │ edging the │
676 │ │ │ write │
677 │ │ │ operation. │
678 │ │ │ This is │
679 │ │ │ the │
680 │ │ │ default │
681 │ │ │ option for │
682 │ │ │ the jour‐ │
683 │ │ │ nal param‐ │
684 │ │ │ eter. │
685 └───────────────────┴────────────┴─────────────────────┘
686
688 ───────────────────────────────────────────────────────────────
689 Constant Key Description
690 ───────────────────────────────────────────────────────────────
691 MONGOC_URI_READCON‐ readconcernlevel The level of isola‐
692 CERNLEVEL tion for read oper‐
693 ations. If the
694 level is left
695 unspecified, the
696 server default will
697 be used. See
698 readConcern in the
699 MongoDB Manual for
700 details.
701 ┌────────────────────┬──────────────────┬─────────────────────┐
702 │ │ │ │
704 When│connected to a repli│ca set, the driver │chooses which membe│r to
705 quer│y using the read pref│erence: │ │
706 │ │ │ │
707 1. C│hoose members whose t│ype matches "readPr│eference". │
708 │ │ │ │
709 2. F│rom these, if ther│e are any tags sets│configured, choose me│mbers
710 m│atching the first tag│set. If there are │none, fall back to the│next
711 t│ag set and so on, unt│il some members are│chosen or the tag set│s are
712 e│xhausted. │ │ │
713 │ │ │ │
714 3. F│rom the chosen serve│rs, distribute qu│eries randomly among│ the
715 s│erver with the fast│est round-trip time│s. These include the s│erver
716 w│ith the fastest time │and any whose round│-trip time is no more │than
717 "│localThresholdMS" slo│wer. │ │
718 │ │ │ │
719 ┌───┼─────────────────┬──┼──────────────────┼─────────────────────┼────┐
720 │Con│stant │ K│ey │ Description │ │
721 ├───┼─────────────────┼──┼──────────────────┼─────────────────────┼────┤
722 │MON│GOC_URI_READ‐ │ r│eadpreference │ Specifies the │ │
723 │PRE│FERENCE │ │ │ replica set read │ │
724 │ │ │ │ │ preference for this │ │
725 │ │ │ │ │ connection. This │ │
726 │ │ │ │ │ setting overrides │ │
727 │ │ │ │ │ any slaveOk value. │ │
728 │ │ │ │ │ The read preference │ │
729 │ │ │ │ │ values are the fol‐ │ │
730 │ │ │ │ │ lowing: │ │
731 │ │ │ │ │ │ │
732 │ │ │ │ │ · primary │ │
733 │ │ │ │ │ (default) │ │
734 │ │ │ │ │ │ │
735 │ │ │ │ │ · prima‐ │ │
736 │ │ │ │ │ ryPre‐ │ │
737 │ │ │ │ │ ferred │ │
738 │ │ │ │ │ │ │
739 │ │ │ │ │ · secondary │ │
740 │ │ │ │ │ │ │
741 │ │ │ │ │ · sec‐ │ │
742 │ │ │ │ │ ondaryPre‐ │ │
743 │ │ │ │ │ ferred │ │
744 │ │ │ │ │ │ │
745 │ │ │ │ │ · nearest │ │
746 ├───┼─────────────────┼──┼──────────────────┼─────────────────────┼────┤
747 │MON│GOC_URI_READ‐ │ r│eadpreferencetags │ A representation of │ │
748 │PRE│FERENCETAGS │ │ │ a tag set. See also │ │
749 │ │ │ │ │ mon‐ │ │
750 │ │ │ │ │ goc-read-prefs-tag-s│ets. │
751 └───┼─────────────────┴──┼──────────────────┼─────────────────────┼────┘
752 │ │ │ │
753 │ │ │ │
754 │ │ │ │
755 │MON‐ │ localthresholdms │ How far to distribute │
757 │GOC_URI_LOCALTHRESH‐ │ │ queries, beyond the │
758 │OLDMS │ │ server with the fastest │
759 │ │ │ round-trip time. By │
760 │ │ │ default, only servers │
761 │ │ │ within 15ms of the │
762 │ │ │ fastest round-trip time │
763 │ │ │ receive queries. │
764 ├─────────────────────┼─────────────────────┼──────────────────────────┤
765 │MONGOC_URI_MAXSTALE‐ │ maxstalenessseconds │ The maximum replication │
766 │NESSSECONDS │ │ lag, in wall clock time, │
767 │ │ │ that a secondary can │
768 │ │ │ suffer and still be eli‐ │
769 │ │ │ gible. The smallest │
770 │ │ │ allowed value for │
771 │ │ │ maxStalenessSeconds is │
772 │ │ │ 90 seconds. │
773 └─────────────────────┴─────────────────────┴──────────────────────────┘
774 NOTE:
776 When connecting to more than one mongos, libmongoc's localThresh‐
777 oldMS applies only to the selection of mongos servers. The threshold
778 for selecting among replica set members in shards is controlled by
779 the mongos's localThreshold command line option.
780
782 For historical reasons, the following options are available. They
783 should however not be used.
784 ┌───────────────────┬─────────┬─────────────────────┐
786 │Constant │ Key │ Description │
787 ├───────────────────┼─────────┼─────────────────────┤
788 │MONGOC_URI_SAFE │ safe │ {true|false} Same │
789 │ │ │ as w={1|0} │
790 ├───────────────────┼─────────┼─────────────────────┤
791 │MONGOC_URI_SLAVEOK │ slaveok │ When set, same as │
792 │ │ │ readPreference=sec‐ │
793 │ │ │ ondaryPreferred │
794 └───────────────────┴─────────┴─────────────────────┘
795
797 MongoDB, Inc
798
800 2017-present, MongoDB, Inc
8011.13.1 Jan 24, 2019 MONGOC_URI_T(3)