- Reference >
- Connection String URI Format
Connection String URI Format¶
This document describes the URI format for defining connections between applications and MongoDB instances in the official MongoDB drivers.
Standard Connection String Format¶
This section describes the standard format of the MongoDB connection URI used to connect to a MongoDB database server. The format is the same for all official MongoDB drivers. For a list of drivers and links to driver documentation, see MongoDB Drivers and Client Libraries.
The following is the standard URI connection scheme:
The components of this string are:
mongodb://
A required prefix to identify that this is a string in the standard connection format.
username:password@
Optional. If specified, the client will attempt to log in to the specific database using these credentials after connecting to the
mongod
instance.host1
This the only required part of the URI. It identifies a server address to connect to. It identifies either a hostname, IP address, or UNIX domain socket.
:port1
Optional. The default value is
:27017
if not specified.hostX
Optional. You can specify as many hosts as necessary. You would specify multiple hosts, for example, for connections to replica sets.
:portX
Optional. The default value is
:27017
if not specified./database
Optional. The name of the database to authenticate if the connection string includes authentication credentials in the form of
username:password@
. If/database
is not specified and the connection string includes credentials, the driver will authenticate to theadmin
database.?options
Connection specific options. See Connection String Options for a full description of these options.
If the connection string does not specify a database/ you must specify a slash (i.e.
/
) between the lasthostN
and the question mark that begins the string of options.
Example
To describe a connection to a replica set named test
,
with the following mongod
hosts:
db1.example.net
on port27017
anddb2.example.net
on port2500
.
You would use a connection string that resembles the following:
Connection String Options¶
This section lists all connection options used in the Standard Connection String Format.The options are not case-sensitive.
Connection options are pairs in the following form:
name=value
. Separate options with the ampersand (i.e. &
)
character. In the following example, a connection uses the
replicaSet
and connectTimeoutMS
options:
Semi-colon separator for connection string arguments
To provide backwards compatibility, drivers currently accept
semi-colons (i.e. ;
) as option separators.
Replica Set Option¶
-
uri.
replicaSet
¶ Specifies the name of the replica set, if the
mongod
is a member of a replica set.When connecting to a replica set it is important to give a seed list of at least two
mongod
instances. If you only provide the connection point of a singlemongod
instance, and omit thereplicaSet
, the client will create a standalone connection.
Connection Options¶
-
uri.
ssl
¶ true
: Initiate the connection with SSL.false
: Initiate the connection without SSL.The default value is
false
.Note
The
ssl
option is not supported by all drivers. See your driver documentation and the Use MongoDB with SSL Connections document.
Connection Pool Options¶
Most drivers implement some kind of connection pooling handle this for you behind the scenes. Some drivers do not support connection pools. See your driver documentation for more information on the connection pooling implementation. These options allow applications to configure the connection pool when connecting to the MongoDB deployment.
-
uri.
maxPoolSize
¶ The maximum number of connections in the connection pool. The default value is
100
.
-
uri.
minPoolSize
¶ The minimum number of connections in the connection pool. The default value is
0
.Note
The
minPoolSize
option is not supported by all drivers. For information on your driver, see the drivers documentation.
-
uri.
maxIdleTimeMS
¶ The maximum number of milliseconds that a connection can remain idle in the pool before being removed and closed.
This option is not supported by all drivers.
-
uri.
waitQueueMultiple
¶ A number that the driver multiples the
maxPoolSize
value to, to provide the maximum number of threads allowed to wait for a connection to become available from the pool. For default values, see the MongoDB Drivers and Client Libraries documentation.
-
uri.
waitQueueTimeoutMS
¶ The maximum time in milliseconds that a thread can wait for a connection to become available. For default values, see the MongoDB Drivers and Client Libraries documentation.
Write Concern Options¶
Write concern describes the kind of assurances that the program:mongod and the driver provide to the application regarding the success and durability of the write operation. For a full explanation of write concern and write operations in general see the: Write Operations:
-
uri.
w
¶ Defines the level and kind of write concern, that the driver uses when calling
getLastError
. This option can take either a number or a string as a value.Options: - -1 – The driver will not acknowledge write operations and will suppress all network or socket errors.
- 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’sjournal
option,journal
overrides thisw
option. - 1 –
Provides basic acknowledgment of write operations.
By specifying
1
, you require that a standalonemongod
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 (string) – For replica sets, if you specify the special
majority
value tow
option, write operations will only return successfully after a majority of the configured replica set members have acknowledged the write operation. - n (number) –
For replica sets, if you specify a number greater than 1, operations with this write concern will only return after this many members of the set have acknowledged the write.
If you set
w
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 (string) –
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.
See Replica Set Tag Set Configuration for more information.
-
uri.
wtimeoutMS
¶ The time in milliseconds to wait for replication to succeed, as specified in the
w
option, before timing out.
-
uri.
journal
¶ Controls whether write operations will wait till the
mongod
acknowledges the write operations and commits the data to the on disk journal.Options: - true (boolean) – Enables journal commit acknowledgment write concern. Equivalent
to specifying the
getLastError
command with thej
option enabled. - false (boolean) –
If you set
journal
totrue
, and specify aw
value less than 1,journal
prevails.If you set
journal
to true, and themongod
does not have journaling enabled, as withnojournal
, thengetLastError
will provide basic receipt acknowledgment (i.e.w:1
), and will include ajnote
field in its return document.
- true (boolean) – Enables journal commit acknowledgment write concern. Equivalent
to specifying the
Read Preference Options¶
Read preferences describe the behavior of read operations with regards to replica sets. These parameters allow you to specify read preferences on a per-connection basis in the connection string:
-
uri.
readPreference
¶ Specifies the replica set read preference for this connection. This setting overrides any
slaveOk
value. The read preference values are the following:For descriptions of each value, see Read Preference Modes.
The default value is
primary
, which sends all read operations to the replica set’s primary.
-
uri.
readPreferenceTags
¶ Specifies a tag set as a comma-separated list of colon-separated key-value pairs. For example:
To specify a list of tag sets, use multiple
readPreferenceTags
. The following specifies two tag sets and an empty tag set:Order matters when using multiple
readPreferenceTags
.
Miscellaneous Configuration¶
-
uri.
uuidRepresentation
¶ Parameters: - standard – The standard binary representation.
- csharpLegacy – The default representation for the C# driver.
- javaLegacy – The default representation for the Java driver.
- pythonLegacy – The default representation for the Python driver.
For the default, see the drivers documentation for your driver.
Note
Not all drivers support the
uuidRepresentation
option. For information on your driver, see the drivers documentation.
Examples¶
Consider the following example MongoDB URI strings, that specify common connections:
Connect to a database server running locally on the default port:
Connect and log in to the
admin
database as usersysop
with the passwordmoon
:Connect and log in to the
records
database as usersysop
with the passwordmoon
:Connect to a UNIX domain socket:
Note
Not all drivers support UNIX domain sockets. For information on your driver, see the drivers documentation.
Connect to a replica set with two members, one on
db1.example.net
and the other ondb2.example.net
:Connect to a replica set with three members running on
localhost
, on ports27017
,27018
, and27019
:Connect to a replica set with three members. Send all writes to the primary and distribute reads to the secondaries:
Connect to a replica set with write concern configured to wait for replication to succeed on at least two members, with a two-second timeout.