Provided by: libmongoc-doc_1.26.0-1.1ubuntu2_all bug

SYNOPSIS

          typedef struct _mongoc_uri_t mongoc_uri_t;

DESCRIPTION

       mongoc_uri_t  provides  an  abstraction  on  top  of the MongoDB connection URI format. It
       provides standardized parsing  as  well  as  convenience  methods  for  extracting  useful
       information such as replica hosts or authorization information.

       See Connection String URI Reference on the MongoDB website for more information.

FORMAT

          mongodb[+srv]://                             <1>
             [username:password@]                      <2>
             host1                                     <3>
             [:port1]                                  <4>
             [,host2[:port2],...[,hostN[:portN]]]      <5>
             [/[database]                              <6>
             [?options]]                               <7>

       1. "mongodb"  is  the  specifier  of the MongoDB protocol. Use "mongodb+srv" with a single
          service name in place of "host1" to specify the initial list of  servers  with  an  SRV
          record.

       2. An optional username and password.

       3. The  only  required  part  of the uri.  This specifies either a hostname, IPv4 address,
          IPv6 address enclosed in "[" and "]", or UNIX domain socket.

       4. An optional port number.  Defaults to :27017.

       5. Extra optional hosts and ports.  You would specify multiple  hosts,  for  example,  for
          connections to replica sets.

       6. The   name   of  the  database  to  authenticate  if  the  connection  string  includes
          authentication credentials.  If /database is not specified and  the  connection  string
          includes credentials, defaults to the 'admin' database.

       7. Connection specific options.

       NOTE:
          Option   names   are   case-insensitive.   Do   not   repeat   the  same  option  (e.g.
          "mongodb://localhost/db?opt=value1&OPT=value2") since this may have unexpected results.

       The MongoDB C Driver  exposes  constants  for  each  supported  connection  option.  These
       constants  make  it  easier to discover connection options, but their string values can be
       used as well.

       For example, the following calls are equal.

          uri = mongoc_uri_new ("mongodb://localhost/?" MONGOC_URI_APPNAME "=applicationName");
          uri = mongoc_uri_new ("mongodb://localhost/?appname=applicationName");
          uri = mongoc_uri_new ("mongodb://localhost/?appName=applicationName");

REPLICA SET EXAMPLE

       To describe a connection to a replica set named 'test' with the following mongod hosts:

       • db1.example.com on port 27017db2.example.com on port 2500

       You would use a connection string that resembles the following.

          mongodb://db1.example.com,db2.example.com:2500/?replicaSet=test

SRV EXAMPLE

       If you have configured an SRV record with a name  like  "_mongodb._tcp.server.example.com"
       whose  records are a list of one or more MongoDB server hostnames, use a connection string
       like this:

          uri = mongoc_uri_new ("mongodb+srv://server.example.com/?replicaSet=rs&appName=applicationName");

       The driver prefixes the service name with "_mongodb._tcp.", then performs a DNS SRV  query
       to  resolve  the service name to one or more hostnames. If this query succeeds, the driver
       performs a DNS TXT query on the service name  (without  the  "_mongodb._tcp"  prefix)  for
       additional URI options configured as TXT records.

       On  Unix,  the  MongoDB  C  Driver  relies on libresolv to look up SRV and TXT records. If
       libresolv is unavailable, then using a "mongodb+srv" URI will  cause  an  error.  If  your
       libresolv  lacks  res_nsearch  then  the driver will fall back to res_search, which is not
       thread-safe.

IPV4 AND IPV6

       If connecting to a hostname that has both IPv4 and IPv6 DNS records, the behavior  follows
       RFC-6555.  A  connection  to  the  IPv6  address is attempted first. If IPv6 fails, then a
       connection is attempted to the IPv4 address. If the connection attempt to  IPv6  does  not
       complete within 250ms, then IPv4 is tried in parallel. Whichever succeeds connection first
       cancels the other. The successful DNS result is cached for 10 minutes.

       As a consequence, attempts to connect to a mongod only listening on IPv4 may be delayed if
       there are both A (IPv4) and AAAA (IPv6) DNS records associated with the host.

       To  avoid  a  delay, configure hostnames to match the MongoDB configuration. That is, only
       create an A record if the mongod is only listening on IPv4.

CONNECTION OPTIONS

┌────────────────────────────────┬──────────────────────┬─────────────────────┬─────────────────────────────────────┐
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
└────────────────────────────────┴──────────────────────┴─────────────────────┴─────────────────────────────────────┘
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
│                                │                      │                     │ mongoc_client_set_ssl_opts()        │
│                                │                      │                     │ mongoc_client_pool_set_ssl_opts().) │
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
└────────────────────────────────┴──────────────────────┴─────────────────────┴─────────────────────────────────────┘

       WARNING:
          Setting any of the *timeoutMS options  above  to  either  0  or  a  negative  value  is
          discouraged  due  to  unspecified  and  inconsistent  behavior.   The  "default  value"
          historically specified as a fallback for 0 or a negative value is NOT  related  to  the
          default  values  for the *timeoutMS options documented above.  The meaning of a timeout
          of 0 or a negative value may vary depending on the operation being executed, even  when
          specified  by  the  same  URI  option.   To  specify the documented default value for a
          *timeoutMS option,  use  the  MONGOC_DEFAULT_*  constants  defined  in  mongoc-client.h
          instead.

AUTHENTICATION OPTIONS

       ┌───────────────────────────────────┬─────────────────────────┬──────────────────────────┐
       │Constant                           │ Key                     │ Description              │
       ├───────────────────────────────────┼─────────────────────────┼──────────────────────────┤
       │MONGOC_URI_AUTHMECHANISM           │ authmechanism           │ Specifies  the mechanism │
       │                                   │                         │ to       use        when │
       │                                   │                         │ authenticating   as  the │
       │                                   │                         │ provided    user.    See │
       │                                   │                         │ Authentication       for │
       │                                   │                         │ supported values.        │
       ├───────────────────────────────────┼─────────────────────────┼──────────────────────────┤
       │MONGOC_URI_AUTHMECHANISMPROPERTIES │ authmechanismproperties │ Certain   authentication │
       │                                   │                         │ mechanisms          have │
       │                                   │                         │ additional  options that │
       │                                   │                         │ can be configured. These │
       │                                   │                         │ options     should    be │
       │                                   │                         │ provided    as     comma │
       │                                   │                         │ separated                │
       │                                   │                         │ option_key:option_value  │
       │                                   │                         │ pair   and  provided  as │
       │                                   │                         │ authMechanismProperties. │
       │                                   │                         │ Specifying    the   same │
       │                                   │                         │ option_key      multiple │
       │                                   │                         │ times    has   undefined │
       │                                   │                         │ behavior.                │
       ├───────────────────────────────────┼─────────────────────────┼──────────────────────────┤
       │MONGOC_URI_AUTHSOURCE              │ authsource              │ The  authSource  defines │
       │                                   │                         │ the database that should │
       │                                   │                         │ be used to  authenticate │
       │                                   │                         │ to. It is unnecessary to │
       │                                   │                         │ provide this option  the │
       │                                   │                         │ database   name  is  the │
       │                                   │                         │ same  as  the   database │
       │                                   │                         │ used in the URI.         │
       └───────────────────────────────────┴─────────────────────────┴──────────────────────────┘

   Mechanism Properties
          ┌────────────────────────────────┬──────────────────────┬──────────────────────────┐
          │Constant                        │ Key                  │ Description              │
          ├────────────────────────────────┼──────────────────────┼──────────────────────────┤
          │MONGOC_URI_CANONICALIZEHOSTNAME │ canonicalizehostname │ Use    the     canonical │
          │                                │                      │ hostname of the service, │
          │                                │                      │ rather     than      its │
          │                                │                      │ configured  alias,  when │
          │                                │                      │ authenticating      with │
          │                                │                      │ Cyrus-SASL Kerberos.     │
          ├────────────────────────────────┼──────────────────────┼──────────────────────────┤
          │MONGOC_URI_GSSAPISERVICENAME    │ gssapiservicename    │ Use  alternative service │
          │                                │                      │ name.  The  default   is │
          │                                │                      │ mongodb.                 │
          └────────────────────────────────┴──────────────────────┴──────────────────────────┘

TLS OPTIONS

┌────────────────────────────────────────────────┬──────────────────────────────────────┬────────────────────────────────────────┐
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
└────────────────────────────────────────────────┴──────────────────────────────────────┴────────────────────────────────────────┘
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
└────────────────────────────────────────────────┴──────────────────────────────────────┴────────────────────────────────────────┘

       See  Configuring TLS for details about these options and about building libmongoc with TLS
       support.

DEPRECATED SSL OPTIONS

       The following options have been deprecated and may be  removed  from  future  releases  of
       libmongoc.

┌───────────────────────────────────────────┬─────────────────────────────────┬──────────────────────────────────────────┬─────────────────────────────┐
├───────────────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
├───────────────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
├───────────────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
├───────────────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
├───────────────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
├───────────────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
└───────────────────────────────────────────┴─────────────────────────────────┴──────────────────────────────────────────┴─────────────────────────────┘

SERVER DISCOVERY, MONITORING, AND SELECTION OPTIONS

       Clients in a mongoc_client_pool_t share a topology  scanner  that  runs  on  a  background
       thread.  The  thread  wakes  every  heartbeatFrequencyMS  (default 10 seconds) to scan all
       MongoDB servers in parallel. Whenever an application operation requires a server  that  is
       not  known--for  example,  if  there  is no known primary and your application attempts an
       insert--the thread rescans all servers every half-second. In  this  situation  the  pooled
       client  waits up to serverSelectionTimeoutMS (default 30 seconds) for the thread to find a
       server   suitable   for   the   operation,   then   returns   an   error    with    domain
       MONGOC_ERROR_SERVER_SELECTION.

       Technically, the total time an operation may wait while a pooled client scans the topology
       is controlled both by serverSelectionTimeoutMS  and  connectTimeoutMS.  The  longest  wait
       occurs  if  the  last  scan begins just at the end of the selection timeout, and a slow or
       down server requires the full connection timeout before the client gives up.

       A non-pooled client is single-threaded. Every heartbeatFrequencyMS,  it  blocks  the  next
       application  operation while it does a parallel scan. This scan takes as long as needed to
       check   the   slowest   server:   roughly   connectTimeoutMS.   Therefore   the    default
       heartbeatFrequencyMS  for  single-threaded  clients is greater than for pooled clients: 60
       seconds.

       By default, single-threaded (non-pooled) clients scan only once when an operation requires
       a  server  that  is not known. If you attempt an insert and there is no known primary, the
       client checks all servers once trying to find it, then succeeds or returns an  error  with
       domain  MONGOC_ERROR_SERVER_SELECTION.  But  if you set serverSelectionTryOnce to "false",
       the  single-threaded  client  loops,  checking  all  servers  every   half-second,   until
       serverSelectionTimeoutMS.

       The  total time an operation may wait for a single-threaded client to scan the topology is
       determined by connectTimeoutMS in  the  try-once  case,  or  serverSelectionTimeoutMS  and
       connectTimeoutMS if serverSelectionTryOnce is set "false".

       ┌────────────────────────────────────┬──────────────────────────┬──────────────────────────┐
       │Constant                            │ Key                      │ Description              │
       ├────────────────────────────────────┼──────────────────────────┼──────────────────────────┤
       │MONGOC_URI_HEARTBEATFREQUENCYMS     │ heartbeatfrequencyms     │ The   interval   between │
       │                                    │                          │ server        monitoring │
       │                                    │                          │ checks.   Defaults    to │
       │                                    │                          │ 10,000ms (10 seconds) in │
       │                                    │                          │ pooled  (multi-threaded) │
       │                                    │                          │ mode,    60,000ms    (60 │
       │                                    │                          │ seconds)  in  non-pooled │
       │                                    │                          │ mode (single-threaded).  │
       ├────────────────────────────────────┼──────────────────────────┼──────────────────────────┤
       │MONGOC_URI_SERVERSELECTIONTIMEOUTMS │ serverselectiontimeoutms │ A       timeout       in │
       │                                    │                          │ milliseconds   to  block │
       │                                    │                          │ for   server   selection │
       │                                    │                          │ before    throwing    an │
       │                                    │                          │ exception.  The  default │
       │                                    │                          │ is     30,0000ms     (30 │
       │                                    │                          │ seconds).                │
       └────────────────────────────────────┴──────────────────────────┴──────────────────────────┘

       │MONGOC_URI_SERVERSELECTIONTRYONCE   │ serverselectiontryonce   │ If  "true",  the  driver │
       │                                    │                          │ scans    the    topology │
       │                                    │                          │ exactly    once    after │
       │                                    │                          │ server  selection fails, │
       │                                    │                          │ then  either  selects  a │
       │                                    │                          │ server   or  returns  an │
       │                                    │                          │ error. If it  is  false, │
       │                                    │                          │ then      the     driver │
       │                                    │                          │ repeatedly searches  for │
       │                                    │                          │ a suitable server for up │
       │                                    │                          │ to                       │
       │                                    │                          │ serverSelectionTimeoutMS │
       │                                    │                          │ milliseconds (pausing  a │
       │                                    │                          │ half    second   between │
       │                                    │                          │ attempts).  The  default │
       │                                    │                          │ for                      │
       │                                    │                          │ serverSelectionTryOnce   │
       │                                    │                          │ is  "false"  for  pooled │
       │                                    │                          │ clients,       otherwise │
       │                                    │                          │ "true".  Pooled  clients │
       │                                    │                          │ ignore                   │
       │                                    │                          │ serverSelectionTryOnce;  │
       │                                    │                          │ they signal  the  thread │
       │                                    │                          │ to  rescan  the topology │
       │                                    │                          │ every half-second  until │
       │                                    │                          │ serverSelectionTimeoutMS │
       │                                    │                          │ expires.                 │
       ├────────────────────────────────────┼──────────────────────────┼──────────────────────────┤
       │MONGOC_URI_SOCKETCHECKINTERVALMS    │ socketcheckintervalms    │ Only applies  to  single │
       │                                    │                          │ threaded  clients.  If a │
       │                                    │                          │ socket has not been used │
       │                                    │                          │ within  this  time,  its │
       │                                    │                          │ connection  is   checked │
       │                                    │                          │ with   a  quick  "hello" │
       │                                    │                          │ call before it  is  used │
       │                                    │                          │ again.    Defaults    to │
       │                                    │                          │ 5,000ms (5 seconds).     │
       ├────────────────────────────────────┼──────────────────────────┼──────────────────────────┤
       │MONGOC_URI_DIRECTCONNECTION         │ directconnection         │ If  "true",  the  driver │
       │                                    │                          │ connects   to  a  single │
       │                                    │                          │ server directly and will │
       │                                    │                          │ not  monitor  additional │
       │                                    │                          │ servers.   If   "false", │
       │                                    │                          │ the    driver   connects │
       │                                    │                          │ based  on  the  presence │
       │                                    │                          │ and    value    of   the │
       │                                    │                          │ replicaSet option.       │
       └────────────────────────────────────┴──────────────────────────┴──────────────────────────┘

       Setting any of the *TimeoutMS options above to 0 will be interpreted as "use  the  default
       value".

CONNECTION POOL OPTIONS

       These  options  govern  the  behavior  of  a  mongoc_client_pool_t.  They are ignored by a
       non-pooled mongoc_client_t.

            ┌──────────────────────────────┬────────────────────┬──────────────────────────┐
            │Constant                      │ Key                │ Description              │
            └──────────────────────────────┴────────────────────┴──────────────────────────┘

            │MONGOC_URI_MAXPOOLSIZE        │ maxpoolsize        │ The  maximum  number  of │
            │                              │                    │ clients   created  by  a │
            │                              │                    │ mongoc_client_pool_t     │
            │                              │                    │ total  (both in the pool │
            │                              │                    │ and  checked  out).  The │
            │                              │                    │ default  value  is  100. │
            │                              │                    │ Once  it   is   reached, │
            │                              │                    │ mongoc_client_pool_pop() │
            │                              │                    │ blocks   until   another │
            │                              │                    │ thread pushes a client.  │
            ├──────────────────────────────┼────────────────────┼──────────────────────────┤
            │MONGOC_URI_MINPOOLSIZE        │ minpoolsize        │ Deprecated.         This │
            │                              │                    │ option's  behavior  does │
            │                              │                    │ not  match its name, and │
            │                              │                    │ its actual behavior will │
            │                              │                    │ likely hurt performance. │
            ├──────────────────────────────┼────────────────────┼──────────────────────────┤
            │MONGOC_URI_MAXIDLETIMEMS      │ maxidletimems      │ Not implemented.         │
            ├──────────────────────────────┼────────────────────┼──────────────────────────┤
            │MONGOC_URI_WAITQUEUEMULTIPLE  │ waitqueuemultiple  │ Not implemented.         │
            ├──────────────────────────────┼────────────────────┼──────────────────────────┤
            │MONGOC_URI_WAITQUEUETIMEOUTMS │ waitqueuetimeoutms │ The maximum time to wait │
            │                              │                    │ for a client  to  become │
            │                              │                    │ available from the pool. │
            └──────────────────────────────┴────────────────────┴──────────────────────────┘

WRITE CONCERN OPTIONS

                    ┌──────────────────────┬────────────┬──────────────────────────┐
                    │Constant              │ Key        │ Description              │
                    └──────────────────────┴────────────┴──────────────────────────┘

                     MONGOC_URI_W            w            Determines   the   write
                                                          concern     (guarantee).
                                                          Valid values:

                                                                 • 0  = The driver
                                                                   will        not
                                                                   acknowledge
                                                                   write
                                                                   operations  but
                                                                   will  pass   or
                                                                   handle      any
                                                                   network     and
                                                                   socket   errors
                                                                   that         it
                                                                   receives to the
                                                                   client. If  you
                                                                   disable   write
                                                                   concern     but
                                                                   enable      the
                                                                   getLastError
                                                                   command’s     w
                                                                   option,       w
                                                                   overrides the w
                                                                   option.

                                                                 • 1  =   Provides
                                                                   basic
                                                                   acknowledgement
                                                                   of        write
                                                                   operations.  By
                                                                   specifying   1,
                                                                   you     require
                                                                   that          a
                                                                   standalone
                                                                   mongod
                                                                   instance,    or
                                                                   the primary for
                                                                   replica   sets,
                                                                   acknowledge all
                                                                   write
                                                                   operations. For
                                                                   drivers
                                                                   released  after
                                                                   the     default
                                                                   write   concern
                                                                   change, this is
                                                                   the     default
                                                                   write   concern
                                                                   setting.

                                                                 • majority  = For
                                                                   replica   sets,
                                                                   if  you specify
                                                                   the     special
                                                                   majority  value
                                                                   to  w   option,
                                                                   write
                                                                   operations will
                                                                   only     return
                                                                   successfully
                                                                   after         a
                                                                   majority of the
                                                                   configured
                                                                   replica     set
                                                                   members    have
                                                                   acknowledged
                                                                   the       write
                                                                   operation.

                                                                 • n = For replica
                                                                   sets,   if  you
                                                                   specify       a
                                                                   number        n
                                                                   greater than 1,
                                                                   operations with
                                                                   this      write
                                                                   concern  return
                                                                   only  after   n
                                                                   members  of the
                                                                   set        have
                                                                   acknowledged
                                                                   the  write.  If
                                                                   you  set n to a
                                                                   number that  is
                                                                   greater    than
                                                                   the  number  of
                                                                   available   set
                                                                   members      or
                                                                   members    that
                                                                   hold      data,
                                                                   MongoDB    will
                                                                   wait,
                                                                   potentially
                                                                   indefinitely,
                                                                   for       these
                                                                   members      to
                                                                   become
                                                                   available.

                                                                 • tags   =    For
                                                                   replica   sets,
                                                                   you can specify
                                                                   a  tag  set  to
                                                                   require    that
                                                                   all  members of
                                                                   the  set   that
                                                                   have these tags
                                                                   configured
                                                                   return
                                                                   confirmation of
                                                                   the       write
                                                                   operation.
                    ├──────────────────────┼────────────┼──────────────────────────┤
                    │MONGOC_URI_WTIMEOUTMS │ wtimeoutms │ The time in milliseconds │
                    │                      │            │ to  wait for replication │
                    │                      │            │ to succeed, as specified │
                    │                      │            │ in  the w option, before │
                    │                      │            │ timing     out.     When │
                    │                      │            │ wtimeoutMS  is  0, write │
                    │                      │            │ operations  will   never │
                    │                      │            │ time out.                │
                    ├──────────────────────┼────────────┼──────────────────────────┤
                    │MONGOC_URI_JOURNAL    │ journal    │ Controls  whether  write │
                    │                      │            │ operations   will   wait │
                    │                      │            │ until     the     mongod │
                    │                      │            │ acknowledges  the  write │
                    │                      │            │ operations  and  commits │
                    │                      │            │ the data to the on  disk │
                    │                      │            │ journal.                 │
                    │                      │            │                          │
                    │                      │            │        • true  = Enables │
                    │                      │            │          journal  commit │
                    │                      │            │          acknowledgement │
                    │                      │            │          write  concern. │
                    │                      │            │          Equivalent   to │
                    │                      │            │          specifying  the │
                    │                      │            │          getLastError    │
                    │                      │            │          command    with │
                    │                      │            │          the   j  option │
                    │                      │            │          enabled.        │
                    │                      │            │                          │
                    │                      │            │        • false  =   Does │
                    │                      │            │          not     require │
                    │                      │            │          that     mongod │
                    │                      │            │          commit    write │
                    │                      │            │          operations   to │
                    │                      │            │          the     journal │
                    │                      │            │          before          │
                    │                      │            │          acknowledging   │
                    │                      │            │          the       write │
                    │                      │            │          operation. This │
                    │                      │            │          is the  default │
                    │                      │            │          option  for the │
                    │                      │            │          journal         │
                    │                      │            │          parameter.      │
                    └──────────────────────┴────────────┴──────────────────────────┘

READ CONCERN OPTIONS

              ┌────────────────────────────┬──────────────────┬──────────────────────────┐
              │Constant                    │ Key              │ Description              │
              ├────────────────────────────┼──────────────────┼──────────────────────────┤
              │MONGOC_URI_READCONCERNLEVEL │ readconcernlevel │ The level  of  isolation │
              │                            │                  │ for  read operations. If │
              │                            │                  │ the   level   is    left │
              │                            │                  │ unspecified,  the server │
              │                            │                  │ default  will  be  used. │
              │                            │                  │ See  readConcern  in the │
              │                            │                  │ MongoDB    Manual    for │
              │                            │                  │ details.                 │
              └────────────────────────────┴──────────────────┴──────────────────────────┘

READ PREFERENCE OPTIONS

       When  connected  to a replica set, the driver chooses which member to query using the read
       preference:

       1. Choose members whose type matches "readPreference".

       2. From these, if there are any tags sets configured, choose members  matching  the  first
          tag set. If there are none, fall back to the next tag set and so on, until some members
          are chosen or the tag sets are exhausted.

       3. From the chosen servers, distribute queries randomly among the server with the  fastest
          round-trip  times.  These  include  the  server  with  the  fastest  time and any whose
          round-trip time is no more than "localThresholdMS" slower.

          ┌───────────────────────────────┬─────────────────────┬─────────────────────────────┐
          │Constant                       │ Key                 │ Description                 │
          ├───────────────────────────────┼─────────────────────┼─────────────────────────────┤
          │MONGOC_URI_READPREFERENCE      │ readpreference      │ Specifies   the  replica    │
          │                               │                     │ set read preference  for    │
          │                               │                     │ this   connection.  This    │
          │                               │                     │ setting  overrides   any    │
          │                               │                     │ secondaryOk  value.  The    │
          │                               │                     │ read  preference  values    │
          │                               │                     │ are the following:          │
          │                               │                     │                             │
          │                               │                     │        • primary            │
          │                               │                     │          (default)          │
          │                               │                     │                             │
          │                               │                     │        • primaryPreferred   │
          │                               │                     │                             │
          │                               │                     │        • secondary          │
          │                               │                     │                             │
          │                               │                     │        • secondaryPreferred │
          │                               │                     │                             │
          │                               │                     │        • nearest            │
          ├───────────────────────────────┼─────────────────────┼─────────────────────────────┤
          │MONGOC_URI_READPREFERENCETAGS  │ readpreferencetags  │ A  representation  of a tag │
          │                               │                     │ set. See also Tag Sets.     │
          ├───────────────────────────────┼─────────────────────┼─────────────────────────────┤
          │MONGOC_URI_LOCALTHRESHOLDMS    │ localthresholdms    │ How   far   to   distribute │
          │                               │                     │ queries,  beyond the server │
          │                               │                     │ with the fastest round-trip │
          │                               │                     │ time.   By   default,  only │
          │                               │                     │ servers within 15ms of  the │
          │                               │                     │ fastest   round-trip   time │
          │                               │                     │ receive queries.            │
          ├───────────────────────────────┼─────────────────────┼─────────────────────────────┤
          │MONGOC_URI_MAXSTALENESSSECONDS │ maxstalenessseconds │ The   maximum   replication │
          │                               │                     │ lag, in  wall  clock  time, │
          │                               │                     │ that a secondary can suffer │
          │                               │                     │ and still be eligible.  The │
          │                               │                     │ smallest  allowed value for │
          │                               │                     │ maxStalenessSeconds  is  90 │
          │                               │                     │ seconds.                    │
          └───────────────────────────────┴─────────────────────┴─────────────────────────────┘

       NOTE:
          When  connecting  to more than one mongos, libmongoc's localThresholdMS applies only to
          the selection of mongos servers. The threshold for selecting among replica set  members
          in shards is controlled by the mongos's localThreshold command line option.

LEGACY OPTIONS

       For  historical  reasons,  the following options are available. They should however not be
       used.

                          ┌────────────────┬──────┬──────────────────────────┐
                          │Constant        │ Key  │ Description              │
                          ├────────────────┼──────┼──────────────────────────┤
                          │MONGOC_URI_SAFE │ safe │ {true|false}   Same   as │
                          │                │      │ w={1|0}                  │
                          └────────────────┴──────┴──────────────────────────┘

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2017-present, MongoDB, Inc