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