Provided by: libmongoc-doc_1.21.0-1build1_all 
NAME
mongoc_uri_t - mongoc_uri_t
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 27017
• db2.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
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Constant Key Default Description
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_RETRYREADS retryreads true If "true" and the
server is a MongoDB
3.6+ standalone,
replica set, or
sharded cluster, the
driver safely retries
a read that failed due
to a network error or
replica set failover.
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_RETRYWRITES retrywrites true if driver built If "true" and the
w/ TLS server is a MongoDB
3.6+ replica set or
sharded cluster, the
driver safely retries
a write that failed
due to a network error
or replica set
failover. Only
inserts, updates of
single documents, or
deletes of single
documents are retried.
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_APPNAME appname Empty (no appname) The client application
name. This value is
used by MongoDB when
it logs connection
information and
profile information,
such as slow queries.
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_TLS tls Empty (not set, same {true|false},
as false) indicating if TLS must
be used. (See also
mongoc_client_set_ssl_opts
and
mongoc_client_pool_set_ssl_opts.)
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_COMPRESSORS compressors Empty (no compressors) Comma separated list of
compressors, if any, to use to
compress the wire protocol
messages. Snappy, zlib, and zstd
are optional build time
dependencies, and enable the
"snappy", "zlib", and "zstd"
values respectively.
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_CONNECTTIMEOUTMS connecttimeoutms 10,000 ms (10 seconds) This setting applies to new
server connections. It is also
used as the socket timeout for
server discovery and monitoring
operations.
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_SOCKETTIMEOUTMS sockettimeoutms 300,000 ms (5 minutes) The time in milliseconds to
attempt to send or receive on a
socket before the attempt times
out.
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_REPLICASET replicaset Empty (no replicaset) The name of the Replica Set that
the driver should connect to.
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_ZLIBCOMPRESSIONLEVEL zlibcompressionlevel -1 When the MONGOC_URI_COMPRESSORS
includes "zlib" this options
configures the zlib compression
level, when the zlib compressor
is used to compress client data.
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_LOADBALANCED loadbalanced false If true, this indicates the
driver is connecting to a MongoDB
cluster behind a load balancer.
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
└─────────────────────────────────┴──────────────────────┴────────────────────────┴───────────────────────────────────┘
Setting any of the *timeoutMS options above to 0 will be interpreted as "use the default value".
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 │ │ │ │
┌─────────────┼─────────────────────────────────┼─┬────────────────────┼─────────────────┬────────────┼───────────────────────────┐
├─────────────┼─────────────────────────────────┼─┼────────────────────┼─────────────────┼────────────┼───────────────────────────┤
--
DEPRECATED SSL│OPTIONS │ │ │
--
CONNECTION│POOL OPTIONS │ │ │
--
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 │ │ │ │
┌─────┼───────────────────────┼────────────┼─────┬────────────────────────┼─────┐
--
READ PREFERENCE OPTIONS │ │ │ │
--
LEGACY OPTIONS │ │ │ │
--
AUTHOR │ │ │ │
MongoDB,│Inc │ │ │
│ │ │ │
COPYRIGHT │ │ │ │