1MONGOC_URI_T(3)                    libmongoc                   MONGOC_URI_T(3)
2
3
4

NAME

6       mongoc_uri_t - mongoc_uri_t
7

SYNOPSIS

9          typedef struct _mongoc_uri_t mongoc_uri_t;
10

DESCRIPTION

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
17       See Connection String URI Reference on the MongoDB website for more in‐
18       formation.
19

FORMAT

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
29       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
33       2. An optional username and password.
34
35       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
39       4. An optional port number.  Defaults to :27017.
40
41       5. Extra  optional  hosts and ports.  You would specify multiple hosts,
42          for example, for connections to replica sets.
43
44       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
49       7. Connection specific options.
50
51       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
56       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
60       For example, the following calls are equal.
61
62          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

REPLICA SET EXAMPLE

67       To describe a connection to a replica set named 'test' with the follow‐
68       ing mongod hosts:
69
70db1.example.com on port 27017
71
72db2.example.com on port 2500
73
74       You would use a connection string that resembles the following.
75
76          mongodb://db1.example.com,db2.example.com:2500/?replicaSet=test
77

SRV EXAMPLE

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
83          uri = mongoc_uri_new ("mongodb+srv://server.example.com/?replicaSet=rs&appName=applicationName");
84
85       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
91       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

IPV4 AND IPV6

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
105       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
109       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

CONNECTION OPTIONS

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
131
132
133
134
135
136
137│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
201
202
203
204
205│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
218       Setting any of the *timeoutMS options above to 0 will be interpreted as
219       "use the default value".
220

AUTHENTICATION OPTIONS

222          ┌────────────────────┬────────────────────┬─────────────────────┐
223          │Constant            │ Key                │ Description         │
224          ├────────────────────┼────────────────────┼─────────────────────┤
225          │MONGOC_URI_AUTH‐    │ authmechanism      │ Specifies the mech‐ │
226          │MECHANISM           │                    │ anism to  use  when │
227          │                    │                    │ authenticating   as │
228          │                    │                    │ the provided  user. │
229          │                    │                    │ See  Authentication │
230          │                    │                    │ for supported  val‐ │
231          │                    │                    │ ues.                │
232          ├────────────────────┼────────────────────┼─────────────────────┤
233          │MONGOC_URI_AUTH‐    │ authmechanismprop‐ │ Certain authentica‐ │
234          │MECHANISMPROPERTIES │ erties             │ tion     mechanisms │
235          │                    │                    │ have additional op‐ │
236          │                    │                    │ tions that  can  be │
237          │                    │                    │ configured.   These │
238          │                    │                    │ options  should  be │
239          │                    │                    │ provided  as  comma │
240          │                    │                    │ separated       op‐ │
241          │                    │                    │ tion_key:op‐        │
242          │                    │                    │ tion_value pair and │
243          │                    │                    │ provided  as  auth‐ │
244          │                    │                    │ MechanismProper‐    │
245          │                    │                    │ ties.               │
246          ├────────────────────┼────────────────────┼─────────────────────┤
247          │MONGOC_URI_AUTH‐    │ authsource         │ The authSource  de‐ │
248          │SOURCE              │                    │ fines  the database │
249          │                    │                    │ that should be used │
250          │                    │                    │ to authenticate to. │
251          │                    │                    │ It  is  unnecessary │
252          │                    │                    │ to provide this op‐ │
253          │                    │                    │ tion  the  database │
254          │                    │                    │ name is the same as │
255          │                    │                    │ the  database  used │
256          │                    │                    │ in the URI.         │
257          └────────────────────┴────────────────────┴─────────────────────┘
258
259   Mechanism Properties
260           ┌────────────────────┬───────────────────┬─────────────────────┐
261           │Constant            │ Key               │ Description         │
262           ├────────────────────┼───────────────────┼─────────────────────┤
263           │MONGOC_URI_CANONI‐  │ canonicalizehost‐ │ Use  the  canonical │
264           │CALIZEHOSTNAME      │ name              │ hostname   of   the │
265           │                    │                   │ service,     rather │
266           │                    │                   │ than its configured │
267           │                    │                   │ alias, when authen‐ │
268           │                    │                   │ ticating       with │
269           │                    │                   │ Cyrus-SASL     Ker‐ │
270           │                    │                   │ beros.              │
271           └────────────────────┴───────────────────┴─────────────────────┘
272
273           │MONGOC_URI_GSSAPIS‐ │ gssapiservicename │ Use     alternative │
274           │ERVICENAME          │                   │ service  name.  The │
275           │                    │                   │ default is mongodb. │
276           └────────────────────┴───────────────────┴─────────────────────┘
277

TLS OPTIONS

279          ┌────────────────────┬─────────────────────┬─────────────────────┐
280          │Constant            │ Key                 │ Description         │
281          ├────────────────────┼─────────────────────┼─────────────────────┤
282          │MONGOC_URI_TLS      │ tls                 │ {true|false}, indi‐ │
283          │                    │                     │ cating if TLS  must │
284          │                    │                     │ be used.            │
285          ├────────────────────┼─────────────────────┼─────────────────────┤
286          │MONGOC_URI_TLSCER‐  │ tlscertificatekey‐  │ Path to PEM format‐ │
287          │TIFICATEKEYFILE     │ file                │ ted  Private   Key, │
288          │                    │                     │ with   its   Public │
289          │                    │                     │ Certificate    con‐ │
290          │                    │                     │ catenated   at  the │
291          │                    │                     │ end.                │
292          ├────────────────────┼─────────────────────┼─────────────────────┤
293          │MONGOC_URI_TLSCER‐  │ tlscertificatekey‐  │ The   password,  if │
294          │TIFICATEKEY‐        │ password            │ any, to use to  un‐ │
295          │FILEPASSWORD        │                     │ lock encrypted Pri‐ │
296          │                    │                     │ vate Key.           │
297          ├────────────────────┼─────────────────────┼─────────────────────┤
298          │MON‐                │ tlscafile           │ One,  or  a  bundle │
299          │GOC_URI_TLSCAFILE   │                     │ of, Certificate Au‐ │
300          │                    │                     │ thorities      whom │
301          │                    │                     │ should  be  consid‐ │
302          │                    │                     │ ered to be trusted. │
303          ├────────────────────┼─────────────────────┼─────────────────────┤
304          │MONGOC_URI_TLSAL‐   │ tlsallowinvalidcer‐ │ Accept  and  ignore │
305          │LOWINVALIDCERTIFI‐  │ tificates           │ certificate verifi‐ │
306          │CATES               │                     │ cation errors (e.g. │
307          │                    │                     │ untrusted   issuer, │
308          │                    │                     │ expired, etc.)      │
309          ├────────────────────┼─────────────────────┼─────────────────────┤
310          │MONGOC_URI_TLSAL‐   │ tlsallowinvalid‐    │ Ignore     hostname │
311          │LOWINVALIDHOSTNAMES │ hostnames           │ verification of the │
312          │                    │                     │ certificate   (e.g. │
313          │                    │                     │ Man  In The Middle, │
314          │                    │                     │ using  valid   cer‐ │
315          │                    │                     │ tificate,  but  is‐ │
316          │                    │                     │ sued  for   another │
317          │                    │                     │ hostname)           │
318          ├────────────────────┼─────────────────────┼─────────────────────┤
319          │MONGOC_URI_TLSINSE‐ │ tlsinsecure         │ {true|false}, indi‐ │
320          │CURE                │                     │ cating  if insecure │
321          │                    │                     │ TLS options  should │
322          │                    │                     │ be  used. Currently │
323          │                    │                     │ this  implies  MON‐ │
324          │                    │                     │ GOC_URI_TLSALLOWIN‐ │
325          │                    │                     │ VALIDCERTIFICATES   │
326          │                    │                     │ and  MONGOC_URI_TL‐ │
327          │                    │                     │ SALLOWINVALIDHOST‐  │
328          │                    │                     │ NAMES.              │
329          ├────────────────────┼─────────────────────┼─────────────────────┤
330          │MONGOC_URI_TLSDIS‐  │ tlsdisablecertifi‐  │ {true|false}, indi‐ │
331          │ABLECERTIFICATERE‐  │ caterevocationcheck │ cates if revocation │
332          │VOCATIONCHECK       │                     │ checking   (CRL   / │
333          │                    │                     │ OCSP)   should   be │
334          │                    │                     │ disabled.           │
335          └────────────────────┴─────────────────────┴─────────────────────┘
336
337
338
339
340
341          │MONGOC_URI_TLSDIS‐  │ tlsdisableocspend‐  │ {true|false}, indi‐ │
342          │ABLEOCSPEND‐        │ pointcheck          │ cates if  OCSP  re‐ │
343          │POINTCHECK          │                     │ sponder   endpoints │
344          │                    │                     │ should not  be  re‐ │
345          │                    │                     │ quested   when   an │
346          │                    │                     │ OCSP  response   is │
347          │                    │                     │ not stapled.        │
348          └────────────────────┴─────────────────────┴─────────────────────┘
349
350       See  configuring_tls for details about these options and about building
351       libmongoc with TLS support.
352

DEPRECATED SSL OPTIONS

354       The following options have been deprecated and may be removed from  fu‐
355       ture releases of libmongoc.
356
357  ┌──────────────────────┬──────────────────┬───────────────────┬──────────────────┐
358  │Constant              │ Key              │ Deprecated For    │ Key              │
359  ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
360  │MONGOC_URI_SSL        │ ssl              │ MONGOC_URI_TLS    │ tls              │
361  ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
362  │MON‐                  │ sslclientcer‐    │ MON‐              │ tlscertifi‐      │
363  │GOC_URI_SSLCLIENTCER‐ │ tificatekeyfile  │ GOC_URI_TLSCER‐   │ catekeyfile      │
364  │TIFICATEKEYFILE       │                  │ TIFICATEKEYFILE   │                  │
365  ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
366  │MON‐                  │ sslclientcer‐    │ MON‐              │ tlscertifi‐      │
367  │GOC_URI_SSLCLIENTCER‐ │ tificatekeypass‐ │ GOC_URI_TLSCER‐   │ catekeypassword  │
368  │TIFICATEKEYPASSWORD   │ word             │ TIFICATEKEY‐      │                  │
369  │                      │                  │ FILEPASSWORD      │                  │
370  ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
371  │MONGOC_URI_SSLCER‐    │ sslcertifi‐      │ MON‐              │ tlscafile        │
372  │TIFICATEAUTHORITYFILE │ cateauthority‐   │ GOC_URI_TLSCAFILE │                  │
373  │                      │ file             │                   │                  │
374  ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
375  │MONGOC_URI_SSLALLOW‐  │ sslallowinvalid‐ │ MONGOC_URI_TLSAL‐ │ tlsallowinvalid‐ │
376  │INVALIDCERTIFICATES   │ certificates     │ LOWINVALIDCER‐    │ certificates     │
377  │                      │                  │ TIFICATES         │                  │
378  ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
379  │MONGOC_URI_SSLALLOW‐  │ sslallowinvalid‐ │ MONGOC_URI_TLSAL‐ │ tlsallowinvalid‐ │
380  │INVALIDHOSTNAMES      │ hostnames        │ LOWINVALIDHOST‐   │ hostnames        │
381  │                      │                  │ NAMES             │                  │
382  └──────────────────────┴──────────────────┴───────────────────┴──────────────────┘
383

SERVER DISCOVERY, MONITORING, AND SELECTION OPTIONS

385       Clients in a mongoc_client_pool_t share a topology scanner that runs on
386       a  background  thread. The thread wakes every heartbeatFrequencyMS (de‐
387       fault 10 seconds) to scan all MongoDB servers in parallel. Whenever  an
388       application operation requires a server that is not known--for example,
389       if there is no known primary  and  your  application  attempts  an  in‐
390       sert--the  thread rescans all servers every half-second. In this situa‐
391       tion the pooled client waits up to serverSelectionTimeoutMS (default 30
392       seconds)  for  the  thread to find a server suitable for the operation,
393       then returns an error with domain MONGOC_ERROR_SERVER_SELECTION.
394
395       Technically, the total time an operation may wait while a pooled client
396       scans  the  topology is controlled both by serverSelectionTimeoutMS and
397       connectTimeoutMS. The longest wait occurs if the last scan begins  just
398       at the end of the selection timeout, and a slow or down server requires
399       the full connection timeout before the client gives up.
400
401       A non-pooled client is single-threaded. Every heartbeatFrequencyMS,  it
402       blocks  the  next  application operation while it does a parallel scan.
403       This scan takes as long as needed to check the slowest server:  roughly
404       connectTimeoutMS.  Therefore  the default heartbeatFrequencyMS for sin‐
405       gle-threaded clients is greater than for pooled clients: 60 seconds.
406
407       By default, single-threaded (non-pooled) clients scan only once when an
408       operation requires a server that is not known. If you attempt an insert
409       and there is no known primary, the client checks all servers once  try‐
410       ing  to  find  it,  then  succeeds or returns an error with domain MON‐
411       GOC_ERROR_SERVER_SELECTION. But if you  set  serverSelectionTryOnce  to
412       "false",  the  single-threaded client loops, checking all servers every
413       half-second, until serverSelectionTimeoutMS.
414
415       The total time an operation may wait for a  single-threaded  client  to
416       scan  the  topology  is  determined by connectTimeoutMS in the try-once
417       case, or serverSelectionTimeoutMS and connectTimeoutMS if  serverSelec‐
418       tionTryOnce is set "false".
419
420          ┌────────────────────┬─────────────────────┬─────────────────────┐
421          │Constant            │ Key                 │ Description         │
422          ├────────────────────┼─────────────────────┼─────────────────────┤
423          │MONGOC_URI_HEART‐   │ heartbeatfrequen‐   │ The   interval  be‐ │
424          │BEATFREQUENCYMS     │ cyms                │ tween server  moni‐ │
425          │                    │                     │ toring  checks. De‐ │
426          │                    │                     │ faults to  10,000ms │
427          │                    │                     │ (10   seconds)   in │
428          │                    │                     │ pooled              │
429          │                    │                     │ (multi-threaded)    │
430          │                    │                     │ mode, 60,000ms  (60 │
431          │                    │                     │ seconds)         in │
432          │                    │                     │ non-pooled     mode │
433          │                    │                     │ (single-threaded).  │
434          ├────────────────────┼─────────────────────┼─────────────────────┤
435          │MONGOC_URI_SERVERS‐ │ serverselection‐    │ A  timeout  in mil‐ │
436          │ELECTIONTIMEOUTMS   │ timeoutms           │ liseconds to  block │
437          │                    │                     │ for  server  selec‐ │
438          │                    │                     │ tion before  throw‐ │
439          │                    │                     │ ing  an  exception. │
440          │                    │                     │ The   default    is │
441          │                    │                     │ 30,0000ms  (30 sec‐ │
442          │                    │                     │ onds).              │
443          ├────────────────────┼─────────────────────┼─────────────────────┤
444          │MONGOC_URI_SERVERS‐ │ serverselectiontry‐ │ If   "true",    the │
445          │ELECTIONTRYONCE     │ once                │ driver   scans  the │
446          │                    │                     │ topology    exactly │
447          │                    │                     │ once  after  server │
448          │                    │                     │ selection    fails, │
449          │                    │                     │ then either selects │
450          │                    │                     │ a server or returns │
451          │                    │                     │ an  error. If it is │
452          │                    │                     │ false,   then   the │
453          │                    │                     │ driver   repeatedly │
454          │                    │                     │ searches   for    a │
455          │                    │                     │ suitable server for │
456          │                    │                     │ up to  serverSelec‐ 
457          │                    │                     │ tionTimeoutMS  mil‐ │
458          │                    │                     │ liseconds  (pausing │
459          │                    │                     │ a  half  second be‐ │
460          │                    │                     │ tween    attempts). │
461          │                    │                     │ The   default   for │
462          │                    │                     │ serverSelectionTry‐ 
463          │                    │                     │ Once is "false" for │
464          │                    │                     │ pooled     clients, │
465          │                    │                     │ otherwise   "true". │
466          │                    │                     │ Pooled clients  ig‐ │
467          │                    │                     │ nore   serverSelec‐ │
468          │                    │                     │ tionTryOnce;   they │
469          │                    │                     │ signal  the  thread │
470          │                    │                     │ to    rescan    the │
471          │                    │                     │ topology      every │
472          │                    │                     │ half-second   until │
473          │                    │                     │ serverSelection‐    │
474          │                    │                     │ TimeoutMS expires.  │
475          └────────────────────┴─────────────────────┴─────────────────────┘
476
477          │MONGOC_URI_SOCK‐    │ socketcheckinter‐   │ Only   applies   to │
478          │ETCHECKINTERVALMS   │ valms               │ single     threaded │
479          │                    │                     │ clients.    If    a │
480          │                    │                     │ socket has not been │
481          │                    │                     │ used  within   this │
482          │                    │                     │ time,  its  connec‐ │
483          │                    │                     │ tion   is   checked │
484          │                    │                     │ with     a    quick │
485          │                    │                     │ "hello" call before │
486          │                    │                     │ it  is  used again. │
487          │                    │                     │ Defaults to 5,000ms │
488          │                    │                     │ (5 seconds).        │
489          ├────────────────────┼─────────────────────┼─────────────────────┤
490          │MONGOC_URI_DIRECT‐  │ directconnection    │ If   "true",    the │
491          │CONNECTION          │                     │ driver  connects to │
492          │                    │                     │ a single server di‐ │
493          │                    │                     │ rectly and will not │
494          │                    │                     │ monitor  additional │
495          │                    │                     │ servers.         If │
496          │                    │                     │ "false", the driver │
497          │                    │                     │ connects  based  on │
498          │                    │                     │ the  presence   and │
499          │                    │                     │ value of the repli‐ 
500          │                    │                     │ caSet option.       │
501          └────────────────────┴─────────────────────┴─────────────────────┘
502
503       Setting any of the *TimeoutMS options above to 0 will be interpreted as
504       "use the default value".
505

CONNECTION POOL OPTIONS

507       These  options  govern the behavior of a mongoc_client_pool_t. They are
508       ignored by a non-pooled mongoc_client_t.
509
510          ┌────────────────────┬────────────────────┬─────────────────────┐
511          │Constant            │ Key                │ Description         │
512          ├────────────────────┼────────────────────┼─────────────────────┤
513          │MONGOC_URI_MAXPOOL‐ │ maxpoolsize        │ The  maximum number │
514          │SIZE                │                    │ of clients  created │
515          │                    │                    │ by      a      mon‐ 
516          │                    │                    │ goc_client_pool_t   
517          │                    │                    │ total  (both in the │
518          │                    │                    │ pool  and   checked │
519          │                    │                    │ out).  The  default │
520          │                    │                    │ value is 100.  Once │
521          │                    │                    │ it is reached, mon‐ 
522          │                    │                    │ goc_client_pool_pop 
523          │                    │                    │ blocks   until  an‐ │
524          │                    │                    │ other thread pushes │
525          │                    │                    │ a client.           │
526          ├────────────────────┼────────────────────┼─────────────────────┤
527          │MONGOC_URI_MINPOOL‐ │ minpoolsize        │ Deprecated.    This │
528          │SIZE                │                    │ option's   behavior │
529          │                    │                    │ does not match  its │
530          │                    │                    │ name,  and  its ac‐ │
531          │                    │                    │ tual behavior  will │
532          │                    │                    │ likely hurt perfor‐ │
533          │                    │                    │ mance.              │
534          ├────────────────────┼────────────────────┼─────────────────────┤
535          │MONGOC_URI_MAXIDLE‐ │ maxidletimems      │ Not implemented.    │
536          │TIMEMS              │                    │                     │
537          ├────────────────────┼────────────────────┼─────────────────────┤
538          │MONGOC_URI_WAIT‐    │ waitqueuemultiple  │ Not implemented.    │
539          │QUEUEMULTIPLE       │                    │                     │
540          └────────────────────┴────────────────────┴─────────────────────┘
541
542
543
544
545          │MONGOC_URI_WAIT‐    │ waitqueuetimeoutms │ The maximum time to │
546          │QUEUETIMEOUTMS      │                    │ wait for  a  client │
547          │                    │                    │ to become available │
548          │                    │                    │ from the pool.      │
549          └────────────────────┴────────────────────┴─────────────────────┘
550

WRITE CONCERN OPTIONS

552               ┌───────────────────┬────────────┬─────────────────────┐
553               │Constant           │ Key        │ Description         │
554               └───────────────────┴────────────┴─────────────────────┘
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613                MONGOC_URI_W         w            Determines      the
614                                                  write       concern
615                                                  (guarantee).  Valid
616                                                  values:
617
618                                                         • 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
646                                                         • 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
683                                                         • 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
711                                                         • 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
753                                                         • 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

READ CONCERN OPTIONS

833           ┌────────────────────┬──────────────────┬─────────────────────┐
834           │Constant            │ Key              │ Description         │
835           └────────────────────┴──────────────────┴─────────────────────┘
836
837
838
839           │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

READ PREFERENCE OPTIONS

852       When  connected  to  a  replica set, the driver chooses which member to
853       query using the read preference:
854
855       1. Choose members whose type matches "readPreference".
856
857       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
862       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
867       ┌────────────────────┬─────────────────────┬──────────────────────────┐
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
901
902
903
904
905
906
907       │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
926       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

LEGACY OPTIONS

933       For historical reasons,  the  following  options  are  available.  They
934       should however not be used.
935
936                   ┌────────────────┬──────┬─────────────────────┐
937                   │Constant        │ Key  │ Description         │
938                   ├────────────────┼──────┼─────────────────────┤
939                   │MONGOC_URI_SAFE │ safe │ {true|false}   Same │
940                   │                │      │ as w={1|0}          │
941                   └────────────────┴──────┴─────────────────────┘
942

AUTHOR

944       MongoDB, Inc
945
947       2017-present, MongoDB, Inc
948
949
950
951
9521.20.0                           Nov 18, 2021                  MONGOC_URI_T(3)
Impressum