1MONGOC_URI_T(3) libmongoc 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 au‐
15 thorization information.
16 See Connection String URI Reference on the MongoDB website for more in‐
18 formation.
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 'ad‐
47 min' 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 at‐
99 tempted 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 │ Default │ Description │
116├───────────────────┼──────────────────┼──────────────────┼────────────────────────────────┤
117│MON‐ │ retryreads │ true │ If "true" and │
118│GOC_URI_RETRYREADS │ │ │ the server is a │
119│ │ │ │ MongoDB 3.6+ │
120│ │ │ │ standalone, │
121│ │ │ │ replica set, or │
122│ │ │ │ sharded cluster, │
123│ │ │ │ the driver │
124│ │ │ │ safely retries a │
125│ │ │ │ read that failed │
126│ │ │ │ due to a network │
127│ │ │ │ error or replica │
128│ │ │ │ set failover. │
129└───────────────────┴──────────────────┴──────────────────┴────────────────────────────────┘
130│MONGOC_URI_RETRY‐ │ retrywrites │ true if driver │ If "true" and │
138│WRITES │ │ built w/ TLS │ the server is a │
139│ │ │ │ MongoDB 3.6+ │
140│ │ │ │ replica set or │
141│ │ │ │ sharded cluster, │
142│ │ │ │ the driver │
143│ │ │ │ safely retries a │
144│ │ │ │ write that │
145│ │ │ │ failed due to a │
146│ │ │ │ network error or │
147│ │ │ │ replica set │
148│ │ │ │ failover. Only │
149│ │ │ │ inserts, updates │
150│ │ │ │ of single docu‐ │
151│ │ │ │ ments, or │
152│ │ │ │ deletes of sin‐ │
153│ │ │ │ gle documents │
154│ │ │ │ are retried. │
155├───────────────────┼──────────────────┼──────────────────┼────────────────────────────────┤
156│MONGOC_URI_APPNAME │ appname │ Empty (no app‐ │ The client ap‐ │
157│ │ │ name) │ plication name. │
158│ │ │ │ This value is │
159│ │ │ │ used by MongoDB │
160│ │ │ │ when it logs │
161│ │ │ │ connection in‐ │
162│ │ │ │ formation and │
163│ │ │ │ profile informa‐ │
164│ │ │ │ tion, such as │
165│ │ │ │ slow queries. │
166├───────────────────┼──────────────────┼──────────────────┼────────────────────────────────┤
167│MONGOC_URI_TLS │ tls │ Empty (not set, │ {true|false}, │
168│ │ │ same as false) │ indicating if │
169│ │ │ │ TLS must be │
170│ │ │ │ used. (See also │
171│ │ │ │ mon‐ │
172│ │ │ │ goc_client_set_ssl_opts │
173│ │ │ │ and mon‐ │
174│ │ │ │ goc_client_pool_set_ssl_opts.) │
175├───────────────────┼──────────────────┼──────────────────┼────────────────────────────────┤
176│MONGOC_URI_COM‐ │ compressors │ Empty (no com‐ │ Comma separated list of com‐ │
177│PRESSORS │ │ pressors) │ pressors, if any, to use to │
178│ │ │ │ compress the wire protocol │
179│ │ │ │ messages. Snappy, zlib, and │
180│ │ │ │ zstd are optional build time │
181│ │ │ │ dependencies, and enable the │
182│ │ │ │ "snappy", "zlib", and "zstd" │
183│ │ │ │ values respectively. │
184├───────────────────┼──────────────────┼──────────────────┼────────────────────────────────┤
185│MONGOC_URI_CON‐ │ connecttimeoutms │ 10,000 ms (10 │ This setting applies to new │
186│NECTTIMEOUTMS │ │ seconds) │ server connections. It is also │
187│ │ │ │ used as the socket timeout for │
188│ │ │ │ server discovery and monitor‐ │
189│ │ │ │ ing operations. │
190├───────────────────┼──────────────────┼──────────────────┼────────────────────────────────┤
191│MONGOC_URI_SOCKET‐ │ sockettimeoutms │ 300,000 ms (5 │ The time in milliseconds to │
192│TIMEOUTMS │ │ minutes) │ attempt to send or receive on │
193│ │ │ │ a socket before the attempt │
194│ │ │ │ times out. │
195├───────────────────┼──────────────────┼──────────────────┼────────────────────────────────┤
196│MONGOC_URI_REPLI‐ │ replicaset │ Empty (no repli‐ │ The name of the Replica Set │
197│CASET │ │ caset) │ that the driver should connect │
198│ │ │ │ to. │
199└───────────────────┴──────────────────┴──────────────────┴────────────────────────────────┘
200│MONGOC_URI_ZLIB‐ │ zlibcompression‐ │ -1 │ When the MONGOC_URI_COMPRES‐ │
206│COMPRESSIONLEVEL │ level │ │ SORS includes "zlib" this op‐ │
207│ │ │ │ tions configures the zlib com‐ │
208│ │ │ │ pression level, when the zlib │
209│ │ │ │ compressor is used to compress │
210│ │ │ │ client data. │
211├───────────────────┼──────────────────┼──────────────────┼────────────────────────────────┤
212│MONGOC_URI_LOAD‐ │ loadbalanced │ false │ If true, this indicates the │
213│BALANCED │ │ │ driver is connecting to a Mon‐ │
214│ │ │ │ goDB cluster behind a load │
215│ │ │ │ balancer. │
216├───────────────────┼──────────────────┼──────────────────┼────────────────────────────────┤
217│MONGOC_URI_SRVMAX‐ │ srvmaxhosts │ 0 │ If zero, the number of hosts │
218│HOSTS │ │ │ in DNS results is unlimited. │
219│ │ │ │ If greater than zero, the num‐ │
220│ │ │ │ ber of hosts in DNS results is │
221│ │ │ │ limited to being less than or │
222│ │ │ │ equal to the given value. │
223└───────────────────┴──────────────────┴──────────────────┴────────────────────────────────┘
224 Setting any of the *timeoutMS options above to 0 will be interpreted as
226 "use the default value".
227
229 ┌────────────────────┬────────────────────┬─────────────────────┐
230 │Constant │ Key │ Description │
231 ├────────────────────┼────────────────────┼─────────────────────┤
232 │MONGOC_URI_AUTH‐ │ authmechanism │ Specifies the mech‐ │
233 │MECHANISM │ │ anism to use when │
234 │ │ │ authenticating as │
235 │ │ │ the provided user. │
236 │ │ │ See Authentication │
237 │ │ │ for supported val‐ │
238 │ │ │ ues. │
239 ├────────────────────┼────────────────────┼─────────────────────┤
240 │MONGOC_URI_AUTH‐ │ authmechanismprop‐ │ Certain authentica‐ │
241 │MECHANISMPROPERTIES │ erties │ tion mechanisms │
242 │ │ │ have additional op‐ │
243 │ │ │ tions that can be │
244 │ │ │ configured. These │
245 │ │ │ options should be │
246 │ │ │ provided as comma │
247 │ │ │ separated op‐ │
248 │ │ │ tion_key:op‐ │
249 │ │ │ tion_value pair and │
250 │ │ │ provided as auth‐ │
251 │ │ │ MechanismProper‐ │
252 │ │ │ ties. Specifying │
253 │ │ │ the same option_key │
254 │ │ │ multiple times has │
255 │ │ │ undefined behavior. │
256 ├────────────────────┼────────────────────┼─────────────────────┤
257 │MONGOC_URI_AUTH‐ │ authsource │ The authSource de‐ │
258 │SOURCE │ │ fines the database │
259 │ │ │ that should be used │
260 │ │ │ to authenticate to. │
261 │ │ │ It is unnecessary │
262 │ │ │ to provide this op‐ │
263 │ │ │ tion the database │
264 │ │ │ name is the same as │
265 │ │ │ the database used │
266 │ │ │ in the URI. │
267 └────────────────────┴────────────────────┴─────────────────────┘
268 Mechanism Properties
270 ────────────────────────────────────────────────────────────────
271 Constant Key Description
272 ────────────────────────────────────────────────────────────────
273 MONGOC_URI_CANONI‐ canonicalizehost‐ Use the canonical
274 CALIZEHOSTNAME name hostname of the
275 service, rather
276 than its configured
277 alias, when authen‐
278 ticating with
279 Cyrus-SASL Ker‐
280 beros.
281 ────────────────────────────────────────────────────────────────
282 MONGOC_URI_GSSAPIS‐ gssapiservicename Use alternative
283 ERVICENAME service name. The
284 default is mongodb.
285 ┌────────────────────┬───────────────────┬─────────────────────┐
286 │ │ │ │
288 ┌┼───────────────────┬┼───────────────────┼┬────────────────────┼┐
289 ││Constant ││Key ││ Description ││
290 ├┼───────────────────┼┼───────────────────┼┼────────────────────┼┤
291 ││MONGOC_URI_TLS ││tls ││ {true|false}, indi‐││
292 ││ ││ ││ cating if TLS must││
293 ││ ││ ││ be used. ││
294 ├┼───────────────────┼┼───────────────────┼┼────────────────────┼┤
295 ││MONGOC_URI_TLSCER‐ ││tlscertificatekey‐ ││ Path to PEM format‐││
296 ││TIFICATEKEYFILE ││file ││ ted Private Key,││
297 ││ ││ ││ with its Public││
298 ││ ││ ││ Certificate con‐││
299 ││ ││ ││ catenated at the││
300 ││ ││ ││ end. ││
301 ├┼───────────────────┼┼───────────────────┼┼────────────────────┼┤
302 ││MONGOC_URI_TLSCER‐ ││tlscertificatekey‐ ││ The password, if││
303 ││TIFICATEKEY‐ ││password ││ any, to use to un‐││
304 ││FILEPASSWORD ││ ││ lock encrypted Pri‐││
305 ││ ││ ││ vate Key. ││
306 ├┼───────────────────┼┼───────────────────┼┼────────────────────┼┤
307 ││MON‐ ││tlscafile ││ One, or a bundle││
308 ││GOC_URI_TLSCAFILE ││ ││ of, Certificate Au‐││
309 ││ ││ ││ thorities whom││
310 ││ ││ ││ should be consid‐││
311 ││ ││ ││ ered to be trusted.││
312 ├┼───────────────────┼┼───────────────────┼┼────────────────────┼┤
313 ││MONGOC_URI_TLSAL‐ ││tlsallowinvalidcer‐││ Accept and ignore││
314 ││LOWINVALIDCERTIFI‐ ││tificates ││ certificate verifi‐││
315 ││CATES ││ ││ cation errors (e.g.││
316 ││ ││ ││ untrusted issuer,││
317 ││ ││ ││ expired, etc.) ││
318 ├┼───────────────────┼┼───────────────────┼┼────────────────────┼┤
319 ││MONGOC_URI_TLSAL‐ ││tlsallowinvalid‐ ││ Ignore hostname││
320 ││LOWINVALIDHOSTNAMES ││hostnames ││ verification of the││
321 ││ ││ ││ certificate (e.g.││
322 ││ ││ ││ Man In The Middle,││
323 ││ ││ ││ using valid cer‐││
324 ││ ││ ││ tificate, but is‐││
325 ││ ││ ││ sued for another││
326 ││ ││ ││ hostname) ││
327 ├┼───────────────────┼┼───────────────────┼┼────────────────────┼┤
328 ││MONGOC_URI_TLSINSE‐ ││tlsinsecure ││ {true|false}, indi‐││
329 ││CURE ││ ││ cating if insecure││
330 ││ ││ ││ TLS options should││
331 ││ ││ ││ be used. Currently││
332 ││ ││ ││ this implies MON‐││
333 ││ ││ ││ GOC_URI_TLSALLOWIN‐││
334 ││ ││ ││ VALIDCERTIFICATES ││
335 ││ ││ ││ and MONGOC_URI_TL‐││
336 ││ ││ ││ SALLOWINVALIDHOST‐ ││
337 ││ ││ ││ NAMES. ││
338 └┴───────────────────┴┴───────────────────┴┴────────────────────┴┘
339 │MONGOC_URI_TLSDIS‐ │ tlsdisablecertifi‐ │ {true|false}, indi‐ │
342 │ABLECERTIFICATERE‐ │ caterevocationcheck │ cates if revocation │
343 │VOCATIONCHECK │ │ checking (CRL / │
344 │ │ │ OCSP) should be │
345 │ │ │ disabled. │
346 ├────────────────────┼─────────────────────┼─────────────────────┤
347 │MONGOC_URI_TLSDIS‐ │ tlsdisableocspend‐ │ {true|false}, indi‐ │
348 │ABLEOCSPEND‐ │ pointcheck │ cates if OCSP re‐ │
349 │POINTCHECK │ │ sponder endpoints │
350 │ │ │ should not be re‐ │
351 │ │ │ quested when an │
352 │ │ │ OCSP response is │
353 │ │ │ not stapled. │
354 └────────────────────┴─────────────────────┴─────────────────────┘
355 See configuring_tls for details about these options and about building
357 libmongoc with TLS support.
358
360 The following options have been deprecated and may be removed from fu‐
361 ture releases of libmongoc.
362 ┌──────────────────────┬──────────────────┬───────────────────┬──────────────────┐
364 │Constant │ Key │ Deprecated For │ Key │
365 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
366 │MONGOC_URI_SSL │ ssl │ MONGOC_URI_TLS │ tls │
367 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
368 │MON‐ │ sslclientcer‐ │ MON‐ │ tlscertifi‐ │
369 │GOC_URI_SSLCLIENTCER‐ │ tificatekeyfile │ GOC_URI_TLSCER‐ │ catekeyfile │
370 │TIFICATEKEYFILE │ │ TIFICATEKEYFILE │ │
371 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
372 │MON‐ │ sslclientcer‐ │ MON‐ │ tlscertifi‐ │
373 │GOC_URI_SSLCLIENTCER‐ │ tificatekeypass‐ │ GOC_URI_TLSCER‐ │ catekeypassword │
374 │TIFICATEKEYPASSWORD │ word │ TIFICATEKEY‐ │ │
375 │ │ │ FILEPASSWORD │ │
376 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
377 │MONGOC_URI_SSLCER‐ │ sslcertifi‐ │ MON‐ │ tlscafile │
378 │TIFICATEAUTHORITYFILE │ cateauthority‐ │ GOC_URI_TLSCAFILE │ │
379 │ │ file │ │ │
380 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
381 │MONGOC_URI_SSLALLOW‐ │ sslallowinvalid‐ │ MONGOC_URI_TLSAL‐ │ tlsallowinvalid‐ │
382 │INVALIDCERTIFICATES │ certificates │ LOWINVALIDCER‐ │ certificates │
383 │ │ │ TIFICATES │ │
384 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
385 │MONGOC_URI_SSLALLOW‐ │ sslallowinvalid‐ │ MONGOC_URI_TLSAL‐ │ tlsallowinvalid‐ │
386 │INVALIDHOSTNAMES │ hostnames │ LOWINVALIDHOST‐ │ hostnames │
387 │ │ │ NAMES │ │
388 └──────────────────────┴──────────────────┴───────────────────┴──────────────────┘
389
391 Clients in a mongoc_client_pool_t share a topology scanner that runs on
392 a background thread. The thread wakes every heartbeatFrequencyMS (de‐
393 fault 10 seconds) to scan all MongoDB servers in parallel. Whenever an
394 application operation requires a server that is not known--for example,
395 if there is no known primary and your application attempts an in‐
396 sert--the thread rescans all servers every half-second. In this situa‐
397 tion the pooled client waits up to serverSelectionTimeoutMS (default 30
398 seconds) for the thread to find a server suitable for the operation,
399 then returns an error with domain MONGOC_ERROR_SERVER_SELECTION.
400 Technically, the total time an operation may wait while a pooled client
402 scans the topology is controlled both by serverSelectionTimeoutMS and
403 connectTimeoutMS. The longest wait occurs if the last scan begins just
404 at the end of the selection timeout, and a slow or down server requires
405 the full connection timeout before the client gives up.
406 A non-pooled client is single-threaded. Every heartbeatFrequencyMS, it
408 blocks the next application operation while it does a parallel scan.
409 This scan takes as long as needed to check the slowest server: roughly
410 connectTimeoutMS. Therefore the default heartbeatFrequencyMS for sin‐
411 gle-threaded clients is greater than for pooled clients: 60 seconds.
412 By default, single-threaded (non-pooled) clients scan only once when an
414 operation requires a server that is not known. If you attempt an insert
415 and there is no known primary, the client checks all servers once try‐
416 ing to find it, then succeeds or returns an error with domain MON‐
417 GOC_ERROR_SERVER_SELECTION. But if you set serverSelectionTryOnce to
418 "false", the single-threaded client loops, checking all servers every
419 half-second, until serverSelectionTimeoutMS.
420 The total time an operation may wait for a single-threaded client to
422 scan the topology is determined by connectTimeoutMS in the try-once
423 case, or serverSelectionTimeoutMS and connectTimeoutMS if serverSelec‐
424 tionTryOnce is set "false".
425 ┌────────────────────┬─────────────────────┬─────────────────────┐
427 │Constant │ Key │ Description │
428 ├────────────────────┼─────────────────────┼─────────────────────┤
429 │MONGOC_URI_HEART‐ │ heartbeatfrequen‐ │ The interval be‐ │
430 │BEATFREQUENCYMS │ cyms │ tween server moni‐ │
431 │ │ │ toring checks. De‐ │
432 │ │ │ faults to 10,000ms │
433 │ │ │ (10 seconds) in │
434 │ │ │ pooled │
435 │ │ │ (multi-threaded) │
436 │ │ │ mode, 60,000ms (60 │
437 │ │ │ seconds) in │
438 │ │ │ non-pooled mode │
439 │ │ │ (single-threaded). │
440 ├────────────────────┼─────────────────────┼─────────────────────┤
441 │MONGOC_URI_SERVERS‐ │ serverselection‐ │ A timeout in mil‐ │
442 │ELECTIONTIMEOUTMS │ timeoutms │ liseconds to block │
443 │ │ │ for server selec‐ │
444 │ │ │ tion before throw‐ │
445 │ │ │ ing an exception. │
446 │ │ │ The default is │
447 │ │ │ 30,0000ms (30 sec‐ │
448 │ │ │ onds). │
449 └────────────────────┴─────────────────────┴─────────────────────┘
450 │MONGOC_URI_SERVERS‐ │ serverselectiontry‐ │ If "true", the │
478 │ELECTIONTRYONCE │ once │ driver scans the │
479 │ │ │ topology exactly │
480 │ │ │ once after server │
481 │ │ │ selection fails, │
482 │ │ │ then either selects │
483 │ │ │ a server or returns │
484 │ │ │ an error. If it is │
485 │ │ │ false, then the │
486 │ │ │ driver repeatedly │
487 │ │ │ searches for a │
488 │ │ │ suitable server for │
489 │ │ │ up to serverSelec‐ │
490 │ │ │ tionTimeoutMS mil‐ │
491 │ │ │ liseconds (pausing │
492 │ │ │ a half second be‐ │
493 │ │ │ tween attempts). │
494 │ │ │ The default for │
495 │ │ │ serverSelectionTry‐ │
496 │ │ │ Once is "false" for │
497 │ │ │ pooled clients, │
498 │ │ │ otherwise "true". │
499 │ │ │ Pooled clients ig‐ │
500 │ │ │ nore serverSelec‐ │
501 │ │ │ tionTryOnce; they │
502 │ │ │ signal the thread │
503 │ │ │ to rescan the │
504 │ │ │ topology every │
505 │ │ │ half-second until │
506 │ │ │ serverSelection‐ │
507 │ │ │ TimeoutMS expires. │
508 ├────────────────────┼─────────────────────┼─────────────────────┤
509 │MONGOC_URI_SOCK‐ │ socketcheckinter‐ │ Only applies to │
510 │ETCHECKINTERVALMS │ valms │ single threaded │
511 │ │ │ clients. If a │
512 │ │ │ socket has not been │
513 │ │ │ used within this │
514 │ │ │ time, its connec‐ │
515 │ │ │ tion is checked │
516 │ │ │ with a quick │
517 │ │ │ "hello" call before │
518 │ │ │ it is used again. │
519 │ │ │ Defaults to 5,000ms │
520 │ │ │ (5 seconds). │
521 ├────────────────────┼─────────────────────┼─────────────────────┤
522 │MONGOC_URI_DIRECT‐ │ directconnection │ If "true", the │
523 │CONNECTION │ │ driver connects to │
524 │ │ │ a single server di‐ │
525 │ │ │ rectly and will not │
526 │ │ │ monitor additional │
527 │ │ │ servers. If │
528 │ │ │ "false", the driver │
529 │ │ │ connects based on │
530 │ │ │ the presence and │
531 │ │ │ value of the repli‐ │
532 │ │ │ caSet option. │
533 └────────────────────┴─────────────────────┴─────────────────────┘
534 Setting any of the *TimeoutMS options above to 0 will be interpreted as
536 "use the default value".
537
539 These options govern the behavior of a mongoc_client_pool_t. They are
540 ignored by a non-pooled mongoc_client_t.
541 ┌────────────────────┬────────────────────┬─────────────────────┐
546 │Constant │ Key │ Description │
547 ├────────────────────┼────────────────────┼─────────────────────┤
548 │MONGOC_URI_MAXPOOL‐ │ maxpoolsize │ The maximum number │
549 │SIZE │ │ of clients created │
550 │ │ │ by a mon‐ │
551 │ │ │ goc_client_pool_t │
552 │ │ │ total (both in the │
553 │ │ │ pool and checked │
554 │ │ │ out). The default │
555 │ │ │ value is 100. Once │
556 │ │ │ it is reached, mon‐ │
557 │ │ │ goc_client_pool_pop │
558 │ │ │ blocks until an‐ │
559 │ │ │ other thread pushes │
560 │ │ │ a client. │
561 ├────────────────────┼────────────────────┼─────────────────────┤
562 │MONGOC_URI_MINPOOL‐ │ minpoolsize │ Deprecated. This │
563 │SIZE │ │ option's behavior │
564 │ │ │ does not match its │
565 │ │ │ name, and its ac‐ │
566 │ │ │ tual behavior will │
567 │ │ │ likely hurt perfor‐ │
568 │ │ │ mance. │
569 ├────────────────────┼────────────────────┼─────────────────────┤
570 │MONGOC_URI_MAXIDLE‐ │ maxidletimems │ Not implemented. │
571 │TIMEMS │ │ │
572 ├────────────────────┼────────────────────┼─────────────────────┤
573 │MONGOC_URI_WAIT‐ │ waitqueuemultiple │ Not implemented. │
574 │QUEUEMULTIPLE │ │ │
575 ├────────────────────┼────────────────────┼─────────────────────┤
576 │MONGOC_URI_WAIT‐ │ waitqueuetimeoutms │ The maximum time to │
577 │QUEUETIMEOUTMS │ │ wait for a client │
578 │ │ │ to become available │
579 │ │ │ from the pool. │
580 └────────────────────┴────────────────────┴─────────────────────┘
581
583 ┌───────────────────┬────────────┬─────────────────────┐
584 │Constant │ Key │ Description │
585 └───────────────────┴────────────┴─────────────────────┘
586 MONGOC_URI_W w Determines the
614 write concern
615 (guarantee). Valid
616 values:
617 • 0 = The
619 driver
620 will not
621 acknowl‐
622 edge write
623 operations
624 but will
625 pass or
626 handle any
627 network
628 and socket
629 errors
630 that it
631 receives
632 to the
633 client. If
634 you dis‐
635 able write
636 concern
637 but enable
638 the get‐
639 LastError
640 command’s
641 w option,
642 w over‐
643 rides the
644 w option.
645 • 1 = Pro‐
647 vides ba‐
648 sic ac‐
649 knowledge‐
650 ment of
651 write op‐
652 erations.
653 By speci‐
654 fying 1,
655 you re‐
656 quire that
657 a stand‐
658 alone mon‐
659 god in‐
660 stance, or
661 the pri‐
662 mary for
663 replica
664 sets, ac‐
665 knowledge
666 all write
667 opera‐
668 tions. For
669 drivers
670 released
671 after the
672 default
673 write con‐
674 cern
675 change,
676 this is
677 the de‐
678 fault
679 write con‐
680 cern set‐
681 ting.
682 • majority =
684 For
685 replica
686 sets, if
687 you spec‐
688 ify the
689 special
690 majority
691 value to w
692 option,
693 write op‐
694 erations
695 will only
696 return
697 success‐
698 fully af‐
699 ter a ma‐
700 jority of
701 the con‐
702 figured
703 replica
704 set mem‐
705 bers have
706 acknowl‐
707 edged the
708 write op‐
709 eration.
710 • n = For
712 replica
713 sets, if
714 you spec‐
715 ify a num‐
716 ber n
717 greater
718 than 1,
719 operations
720 with this
721 write con‐
722 cern re‐
723 turn only
724 after n
725 members of
726 the set
727 have ac‐
728 knowledged
729 the write.
730 If you set
731 n to a
732 number
733 that is
734 greater
735 than the
736 number of
737 available
738 set mem‐
739 bers or
740 members
741 that hold
742 data, Mon‐
743 goDB will
744 wait, po‐
745 tentially
746 indefi‐
747 nitely,
748 for these
749 members to
750 become
751 available.
752 • tags = For
754 replica
755 sets, you
756 can spec‐
757 ify a tag
758 set to re‐
759 quire that
760 all mem‐
761 bers of
762 the set
763 that have
764 these tags
765 configured
766 return
767 confirma‐
768 tion of
769 the write
770 operation.
771 ├───────────────────┼────────────┼─────────────────────┤
772 │MONGOC_URI_WTIME‐ │ wtimeoutms │ The time in mil‐ │
773 │OUTMS │ │ liseconds to wait │
774 │ │ │ for replication to │
775 │ │ │ succeed, as speci‐ │
776 │ │ │ fied in the w op‐ │
777 │ │ │ tion, before timing │
778 │ │ │ out. When wtime‐ │
779 │ │ │ outMS is 0, write │
780 │ │ │ operations will │
781 │ │ │ never time out. │
782 ├───────────────────┼────────────┼─────────────────────┤
783 │MONGOC_URI_JOURNAL │ journal │ Controls whether │
784 │ │ │ write operations │
785 │ │ │ will wait until the │
786 │ │ │ mongod acknowledges │
787 │ │ │ the write opera‐ │
788 │ │ │ tions and commits │
789 │ │ │ the data to the on │
790 │ │ │ disk journal. │
791 │ │ │ │
792 │ │ │ • true = │
793 │ │ │ Enables │
794 │ │ │ journal │
795 │ │ │ commit ac‐ │
796 │ │ │ knowledge‐ │
797 │ │ │ ment write │
798 │ │ │ concern. │
799 │ │ │ Equivalent │
800 │ │ │ to speci‐ │
801 │ │ │ fying the │
802 │ │ │ getLastEr‐ │
803 │ │ │ ror com‐ │
804 │ │ │ mand with │
805 │ │ │ the j op‐ │
806 │ │ │ tion en‐ │
807 │ │ │ abled. │
808 │ │ │ │
809 │ │ │ • false = │
810 │ │ │ Does not │
811 │ │ │ require │
812 │ │ │ that mon‐ │
813 │ │ │ god commit │
814 │ │ │ write op‐ │
815 │ │ │ erations │
816 │ │ │ to the │
817 │ │ │ journal │
818 │ │ │ before ac‐ │
819 │ │ │ knowledg‐ │
820 │ │ │ ing the │
821 │ │ │ write op‐ │
822 │ │ │ eration. │
823 │ │ │ This is │
824 │ │ │ the de‐ │
825 │ │ │ fault op‐ │
826 │ │ │ tion for │
827 │ │ │ the jour‐ │
828 │ │ │ nal param‐ │
829 │ │ │ eter. │
830 └───────────────────┴────────────┴─────────────────────┘
831
833 ┌────────────────────┬──────────────────┬─────────────────────┐
834 │Constant │ Key │ Description │
835 └────────────────────┴──────────────────┴─────────────────────┘
836 │MONGOC_URI_READCON‐ │ readconcernlevel │ The level of isola‐ │
840 │CERNLEVEL │ │ tion for read oper‐ │
841 │ │ │ ations. If the │
842 │ │ │ level is left un‐ │
843 │ │ │ specified, the │
844 │ │ │ server default will │
845 │ │ │ be used. See │
846 │ │ │ readConcern in the │
847 │ │ │ MongoDB Manual for │
848 │ │ │ details. │
849 └────────────────────┴──────────────────┴─────────────────────┘
850
852 When connected to a replica set, the driver chooses which member to
853 query using the read preference:
854 1. Choose members whose type matches "readPreference".
856 2. From these, if there are any tags sets configured, choose members
858 matching the first tag set. If there are none, fall back to the next
859 tag set and so on, until some members are chosen or the tag sets are
860 exhausted.
861 3. From the chosen servers, distribute queries randomly among the
863 server with the fastest round-trip times. These include the server
864 with the fastest time and any whose round-trip time is no more than
865 "localThresholdMS" slower.
866 ┌────────────────────┬─────────────────────┬──────────────────────────┐
868 │Constant │ Key │ Description │
869 ├────────────────────┼─────────────────────┼──────────────────────────┤
870 │MONGOC_URI_READ‐ │ readpreference │ Specifies the │
871 │PREFERENCE │ │ replica set read │
872 │ │ │ preference for this │
873 │ │ │ connection. This │
874 │ │ │ setting overrides │
875 │ │ │ any secondaryOk │
876 │ │ │ value. The read │
877 │ │ │ preference values │
878 │ │ │ are the following: │
879 │ │ │ │
880 │ │ │ • primary │
881 │ │ │ (default) │
882 │ │ │ │
883 │ │ │ • prima‐ │
884 │ │ │ ryPre‐ │
885 │ │ │ ferred │
886 │ │ │ │
887 │ │ │ • secondary │
888 │ │ │ │
889 │ │ │ • sec‐ │
890 │ │ │ ondaryPre‐ │
891 │ │ │ ferred │
892 │ │ │ │
893 │ │ │ • nearest │
894 ├────────────────────┼─────────────────────┼──────────────────────────┤
895 │MONGOC_URI_READ‐ │ readpreferencetags │ A representation of │
896 │PREFERENCETAGS │ │ a tag set. See also │
897 │ │ │ mon‐ │
898 │ │ │ goc-read-prefs-tag-sets. │
899 └────────────────────┴─────────────────────┴──────────────────────────┘
900 │MONGOC_URI_LO‐ │ localthresholdms │ How far to distribute │
908 │CALTHRESHOLDMS │ │ queries, beyond the │
909 │ │ │ server with the fastest │
910 │ │ │ round-trip time. By de‐ │
911 │ │ │ fault, only servers │
912 │ │ │ within 15ms of the │
913 │ │ │ fastest round-trip time │
914 │ │ │ receive queries. │
915 ├────────────────────┼─────────────────────┼──────────────────────────┤
916 │MONGOC_URI_MAXSTAL‐ │ maxstalenessseconds │ The maximum replication │
917 │ENESSSECONDS │ │ lag, in wall clock time, │
918 │ │ │ that a secondary can │
919 │ │ │ suffer and still be eli‐ │
920 │ │ │ gible. The smallest al‐ │
921 │ │ │ lowed value for maxStal‐ │
922 │ │ │ enessSeconds is 90 sec‐ │
923 │ │ │ onds. │
924 └────────────────────┴─────────────────────┴──────────────────────────┘
925 NOTE:
927 When connecting to more than one mongos, libmongoc's localThresh‐
928 oldMS applies only to the selection of mongos servers. The threshold
929 for selecting among replica set members in shards is controlled by
930 the mongos's localThreshold command line option.
931
933 For historical reasons, the following options are available. They
934 should however not be used.
935 ┌────────────────┬──────┬─────────────────────┐
937 │Constant │ Key │ Description │
938 ├────────────────┼──────┼─────────────────────┤
939 │MONGOC_URI_SAFE │ safe │ {true|false} Same │
940 │ │ │ as w={1|0} │
941 └────────────────┴──────┴─────────────────────┘
942
944 MongoDB, Inc
945
947 2017-present, MongoDB, Inc
9481.21.1 Mar 02, 2022 MONGOC_URI_T(3)