Connection String URI Format

This document describes the URI formats for defining connectionsbetween applications and MongoDB instances in the official MongoDBdrivers. For a list of drivers and links todriver documentation, see drivers.

Connection String Formats

You can specify the MongoDB connection string using either:

• the Standard Connection String Format or
• the DNS Seedlist Connection Format.

Standard Connection String Format

This section describes the standard format of the MongoDB connectionURI used to connect to a MongoDB deployment: standalone, replica set,or a sharded cluster.

The standard URI connection scheme has the form:

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

Examples

• Standalone
• Replica Set
• Sharded Cluster

• For a standalone:

mongodb://mongodb0.example.com:27017/admin

• For a standalone that enforces access control:

mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017/admin

If the username or password includes the at sign @, colon :,slash /, or the percent sign % character, use percentencoding.

Note

For a replica set, specify the hostname(s) of the mongodinstance(s) as listed in the replica set configuration.

For a replica set, include the replicaSetoption.

• For a replica set:

mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/admin?replicaSet=myRepl

• For a replica set that enforces access control, includeuser credentials:

mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/admin?replicaSet=myRepl

If the username or password includes the at sign @, colon :,slash /, or the percent sign % character, use percentencoding.

Note

For a connection string to a sharded cluster, specifymongos hosts in the connection string.

• For a sharded cluster:

mongodb://mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017/admin

• For a sharded cluster that enforces accesscontrol, includeuser credentials:

mongodb://myDBReader:D1fficultP%40ssw0rd@mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017/admin

If the username or password includes the at sign @, colon :,slash /, or the percent sign % character, use percentencoding.

For more examples, see Examples.

Components

The standard URI connection string includes the following components:

DNS Seedlist Connection Format

New in version 3.6.

In addition to the standard connection format, MongoDB supports aDNS-constructed seed list. Using DNS toconstruct the available servers list allows more flexibility ofdeployment and the ability to change the servers in rotation withoutreconfiguring clients.

In order to leverage the DNS seedlist, use a connection string prefix ofmongodb+srv: rather than the standard mongodb:. The +srvindicates to the client that the hostname that follows corresponds to aDNS SRV record. The driver or mongo shell will thenquery the DNS for the record to determine which hosts are running themongod instances.

Note

Use of the +srv connection string modifierautomatically sets the tls (or the equivalentssl) option to true for the connection. You canoverride this behavior by explicitly setting the tls(or the equivalent ssl) option to false withtls=false (or ssl=false) in the query string.

The following example shows a typical connection string for a DNSseedlist connection string:

mongodb+srv://server.example.com/

The corresponding DNS configuration might resemble:

Record                            TTL   Class    Priority Weight Port  Target
_mongodb._tcp.server.example.com. 86400 IN SRV   0        5      27317 mongodb1.example.com.
_mongodb._tcp.server.example.com. 86400 IN SRV   0        5      27017 mongodb2.example.com.

Important

The hostnames returned in SRV records must share the same parentdomain (in this example, example.com) as the given hostname. Ifthe parent domains and hostname do not match, you will not be able toconnect.

Like the standard connection string, the DNS seedlist connection stringsupports specifying options as a query string. With a DNS seedlistconnection string, you can also specify the following options via aTXT record:

• replicaSet
• authSource

You may only specify one TXT record per mongod instance.If multiple TXT records appear in the DNS and/or if the TXTrecord contains an option other than replicaSet or authSource,the client will return an error.

The TXT record for the server.example.com DNS entry would resemble:

Record              TTL   Class    Text
server.example.com. 86400 IN TXT   "replicaSet=mySet&authSource=authDB"

Taken together, the DNS SRV records and the options specified in the TXTrecord resolve to the following standard format connection string:

mongodb://mongodb1.example.com:27317,mongodb2.example.com:27017/?replicaSet=mySet&authSource=authDB

You can override the options specified in a TXT record by passing the optionin the query string. In the following example, the query string has providedan override for the authSource option configured in the TXT recordof the DNS entry above.

mongodb+srv://server.example.com/?connectTimeoutMS=300000&authSource=aDifferentAuthDB

Given the override for the authSource, the equivalent connectionstring in the standard format would be:

mongodb://mongodb1.example.com:27317,mongodb2.example.com:27017/?connectTimeoutMS=300000&replicaSet=mySet&authSource=aDifferentAuthDB

Note

The mongodb+srv option will fail if there is no available DNSwith records that correspond to the hostname identified in theconnection string. In addition, use of the +srv connection string modifierautomatically sets the tls (or the equivalentssl) option to true for the connection. You canoverride this behavior by explicitly setting the tls(or the equivalent ssl) option to false withtls=false (or ssl=false) in the query string.

See

Connect to a Replica Set Using the DNS Seedlist Connection Format provides an example ofconnecting the mongo shell to a replica set usingthe DNS Seedlist Connection Format.

Connection String Options

This section lists all connection options.

Connection options are pairs in the following form: name=value.

• The option name is case insensitive when using a driver.
• The option name is case insensitive when using a version 4.2+mongo shell.
• The option name is case sensitive when using a version 4.0 andearlier mongo shell.
• The value is always case sensitive.

Separate options with the ampersand (i.e. &) charactername1=value1&name2=value2. In the following example, aconnection includes the replicaSet andconnectTimeoutMS options:

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

Semi-colon separator for connection string arguments

To provide backwards compatibility, drivers currently acceptsemi-colons (i.e. ;) as option separators.

Replica Set Option

The following connection string to a replica set named myRepl withmembers running on the specified hosts:

mongodb://db0.example.com:27017,db1.example.com:27017,db2.example.com:27017/admin?replicaSet=myRepl

Connection Options

TLS Options

The following connection string to a replica set includestls=true option (available starting in MongoDB 4.2):

mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&tls=true

Alternatively, you can also use the equivalent ssl=true option:

mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&ssl=true

Timeout Options

Compression Options

Connection Pool Options

Most drivers implement some kind of connection pool handling.Some drivers do not support connectionpools. See your driver documentationfor more information on the connection pooling implementation. Theseoptions allow applications to configure the connection pool whenconnecting to the MongoDB deployment.

Write Concern Options

Write concern describes the level ofacknowledgment requested from MongoDB. The write concern option issupported by the:

• MongoDB drivers
• mongo shell
• mongofiles
• mongoimport
• mongorestore

You can specify the write concern both in the connection string andas a parameter to methods like insert or update. If thewrite concern is specified in both places, the method parameteroverrides the connection-string setting.

The following connection string to a replica set specifies"majority" write concern and a 5 secondtimeout using the wtimeoutMS write concern parameter:

mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&w=majority&wtimeoutMS=5000

For more information, see Write Concern.

readConcern Options

New in version 3.2: For the WiredTiger storage engine, MongoDB 3.2 introduces thereadConcern option for replica sets and replica set shards.

Read Concern allows clients to choose a level ofisolation for their reads from replica sets.

The following connection string to a replica set specifiesreadConcernLevel=majority:

mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&readConcernLevel=majority

For more information, see Read Concern.

Read Preference Options

Read preferences describe thebehavior of read operations with regards to replica sets. These parameters allow you to specify read preferenceson a per-connection basis in the connection string.

For example:

• The following connection string to a replica set specifiessecondary read preference mode and amaxStalenessSeconds value of 120 seconds:

mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&readPreference=secondary&maxStalenessSeconds=120

• The following connection string to a sharded cluster specifiessecondary read preference mode and amaxStalenessSeconds value of 120 seconds:

mongodb://mongos1.example.com,mongos2.example.com/?readPreference=secondary&maxStalenessSeconds=120

• The following connection string to a sharded cluster specifiessecondary read preference mode as well as threereadPreferenceTags:

mongodb://mongos1.example.com,mongos2.example.com/?readPreference=secondary&readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=dc:ny&readPreferenceTags=

Order matters when using multiple readPreferenceTags. ThereadPreferenceTags are tried in order until a match is found. Oncefound, that specification is used to find all eligible matchingmembers and any remaining readPreferenceTags are ignored.For details, see Order of Tag Matching.

For more information, see Read preferences.

Authentication Options

The following connection string to a replica set specifies theauthSource to the admin database. That is the usercredentials are authenticated to the admin database.

mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/test?replicaSet=myRepl&authSource=admin

If the username or password includes the at sign @, colon :,slash /, or the percent sign % characters, use percentencoding.

Server Selection and Discovery Options

MongoDB provides the following options to configure how MongoDB driversand mongos instances select a server to which to direct reador write operations.

Miscellaneous Configuration

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 thedefault port:

mongodb://localhost

admin Database

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

mongodb://sysop:moon@localhost

records Database

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

mongodb://sysop:moon@localhost/records

UNIX Domain Socket

Use a URL encoded connection string when connecting to a UNIX domainsocket.

The following connects to a UNIX domain socket with file path/tmp/mongodb-27017.sock:

mongodb://%2Ftmp%2Fmongodb-27017.sock

Note

Not all drivers support UNIX domain sockets. For informationon your driver, see the driversdocumentation.

Replica Set with Members on Different Machines

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

Note

For a replica set, specify the hostname(s) of the mongodinstance(s) as listed in the replica set configuration.

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

Replica Set with Members on localhost

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

Note

For a replica set, specify the hostname(s) of the mongodinstance(s) as listed in the replica set configuration.

mongodb://localhost,localhost:27018,localhost:27019/?replicaSet=test

Replica Set with Read Distribution

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

Note

For a replica set, specify the hostname(s) of the mongodinstance(s) as listed in the replica set configuration.

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

Replica Set with a High Level of Write Concern

The following connects to a replica set with write concern configured to waitfor replication to succeed across a majority of the data-bearing votingmembers, with a two-second timeout.

Note

For a replica set, specify the hostname(s) of the mongodinstance(s) as listed in the replica set configuration.

mongodb://example1.com,example2.com,example3.com/?replicaSet=test&w=majority&wtimeoutMS=2000

Sharded Cluster

The following connects to a sharded cluster with three mongos instances:

mongodb://router1.example.com:27017,router2.example2.com:27017,router3.example3.com:27017/