• 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:

copy

mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]

The components of this string are:

1. mongodb://

   A required prefix to identify that this is a string in the standard connection format.

2. 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.

3. 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.

4. :port1

   Optional. The default value is :27017 if not specified.

5. hostX

   Optional. You can specify as many hosts as necessary. You would specify multiple hosts, for example, for connections to replica sets.

6. :portX

   Optional. The default value is :27017 if not specified.

7. /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 the admin database.

8. ?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 last hostN 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 port 27017 and
• db2.example.net on port 2500.

You would use a connection string that resembles the following:

copy

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

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:

copy

mongodb://db1.example.net,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000

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 single mongod instance, and omit the replicaSet, 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 Connect to MongoDB with SSL document.

uri.connectTimeoutMS

The time in milliseconds to attempt a connection before timing out. The default is never to timeout, though different drivers might vary. See the driver documentation.

uri.socketTimeoutMS

The time in milliseconds to attempt a send or receive on a socket before the attempt times out. The default is never to timeout, though different drivers might vary. See the driver documentation.

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.

Option	Type	Description
-1	number	The driver will not acknowledge write operations and will suppress all network or socket errors.
0	number	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	number	Provides basic acknowledgment 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	string	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	number	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	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. When wtimeoutMS is 0, write operations will never time out.

uri.journal

Controls whether write operations will wait until the mongod acknowledges the write operations and commits the data to the on disk journal.

Option	Type	Description
true	Boolean	Enables journal commit acknowledgment write concern. Equivalent to specifying the getLastError command with the j option enabled.
false	Boolean	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.

If you set journal to true, and specify a w value less than 1, journal prevails.

If you set journal to true, and the mongod does not have journaling enabled, as with nojournal, then getLastError will provide basic receipt acknowledgment (i.e. w:1), and will include a jnote field in its return document.

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:

• primary
• primaryPreferred
• secondary
• secondaryPreferred
• nearest

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:

copy

dc:ny,rack:1

To specify a list of tag sets, use multiple readPreferenceTags. The following specifies two tag sets and an empty tag set:

copy

readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags=

Order matters when using multiple readPreferenceTags.

Miscellaneous Configuration

uri.uuidRepresentation

Option	Description
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

The following provide example URI strings for common connection targets.

Database Server Running Locally

The following connects to a database server running locally on the default port:

copy

mongodb://localhost

admin Database

The following connects and logs in to the admin database as user sysop with the password moon:

copy

mongodb://sysop:moon@localhost

records Database

The following connects and logs in to the records database as user sysop with the password moon:

copy

mongodb://sysop:moon@localhost/records

UNIX Domain Socket

The following connects to a UNIX domain socket:

copy

mongodb:///tmp/mongodb-27017.sock

Note

Not all drivers support UNIX domain sockets. For information on your driver, see the drivers documentation.

Replica Set with Members on Different Machines

The following connects to a replica set with two members, one on db1.example.net and the other on db2.example.net:

copy

mongodb://db1.example.net,db2.example.com

Replica Set with Members on localhost

The following connects to a replica set with three members running on localhost on ports 27017, 27018, and 27019:

copy

mongodb://localhost,localhost:27018,localhost:27019

Replica Set with Read Distribution

The following connects to a replica set with three members and distributes reads to the secondaries:

copy

mongodb://example1.com,example2.com,example3.com/?readPreference=secondary

Replica Set with a High Level of Write Concern

The following connects to a replica set with write concern configured to wait for replication to succeed on at least two members, with a two-second timeout.

copy

mongodb://example1.com,example2.com,example3.com/?w=2&wtimeoutMS=2000

←   MongoDB Limits and Thresholds Glossary  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.