Connection String Formats

You can specify the MongoDB connection string by using one of the following formats:

SRV Connection Format: A connection string with a hostname that corresponds to a DNS SRV record. Your driver or mongosh queries the record to determine which hosts are running the mongod or mongos instances.
Standard Connection String Format: A connection string that specifies all hosts that are running the mongod or mongos instances.

MongoDB Atlas clusters use SRV connection format unless you connect to an online archive.

To connect directly to a host and port specified in a connection string, set the directConnection option to true. For full details about directConnection and the other connection string options, see Connection String Options.

SRV Connection Format

MongoDB supports a DNS-constructed seed list. Using DNS to construct the available servers list allows more flexibility of deployment and the ability to change the servers in rotation without reconfiguring clients.

The SRV URI connection scheme has the following form:

mongodb+srv://[username:password@]host[/[defaultauthdb][?options]]

For more examples, see these pages:

Connection String Components

A connection string includes the following components:

Component

Description

mongodb:// or mongodb+srv://

A required prefix to identify that this is a string in the standard connection format (mongodb://) or SRV connection format (mongodb+srv://). To learn more about each format, see Standard Connection String Format and SRV Connection Format.

username:password@

Optional. Authentication credentials.

If specified, the client will attempt to authenticate the user to the authSource. If authSource is unspecified, the client will attempt to authenticate the user to the defaultauthdb. And if the defaultauthdb is unspecified, to the admin database.

If the username or password includes the following characters, those characters must be converted using percent encoding:

$ : / ? # [ ] @

Note

When you use the +srv connection string modifier, the connection automatically sets the tls (or the equivalent ssl) option to true. To override this behavior, explicitly set the tls (or the equivalent ssl) option to false in the connection query string.

When using the +srv format, you must specify the hostname, domain, and top-level domain (TLD) in the following format: <hostname>.<domain>.<TLD>. This table shows how the placeholders correspond to example values:

Placeholder	Example
`<hostname>`	`server`
`<domain>`	`example`
`<TLD>`	`com`
`<hostname>.<domain>.<TLD>`	`server.example.com`

This example shows a DNS seed list connection string that correctly uses the <hostname>.<domain>.<TLD> format. It authenticates as user myDatabaseUser with the password D1fficultP%40ssw0rd:

mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/

The corresponding DNS configuration resembles:

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.

Individual SRV records must be in _mongodb._tcp.<hostname>.<domain>.<TLD> format.

When a client connects to a member of the seed list, the client retrieves a list of replica set members it can connect to. Clients often use DNS aliases in their seed lists, which means the host may return a server list that differs from the original seed list. If this happens, clients use the hostnames provided by the replica set rather than the hostnames listed in the seed list to ensure that replica set members can be reached via the hostnames in the resulting replica set config.

Important

The hostnames returned in SRV records must share the same parent domain (in this example, example.com) as the given hostname. If the parent domains and hostname do not match, you can't connect.

Like the standard connection string, the DNS seed list connection string supports specifying options as a query string. With a DNS seed list connection string, you can also specify the following options via a TXT record:

replicaSet
authSource

You can only specify one TXT record per mongod instance. If multiple TXT records appear in the DNS or if the TXT record contains an option other than replicaSet or authSource, the client returns an error.

The TXT record for the server.example.com DNS entry resembles the following example:

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 TXT record resolve to the following standard format connection string:

mongodb://myDatabaseUser:D1fficultP%[email protected]:27317,mongodb2.example.com:27017/?replicaSet=mySet&authSource=authDB

To override the options specified in a TXT record, specify the option in the query string. For example, the following query string overrides the authSource option configured in the TXT record of the previous DNS entry.

mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?connectTimeoutMS=300000&authSource=aDifferentAuthDB

Given the override for the authSource, the equivalent connection string in the standard format would resemble the following example:

mongodb://myDatabaseUser:D1fficultP%[email protected]:27317,mongodb2.example.com:27017/?connectTimeoutMS=300000&replicaSet=mySet&authSource=aDifferentAuthDB

Note

The mongodb+srv option fails if there is no available DNS with records that correspond to the hostname identified in the connection string. If you use the +srv connection string modifier, the tls (or the equivalent ssl) option is set to true for the connection. You can override this behavior by explicitly setting the tls (or the equivalent ssl) option to false with tls=false (or ssl=false) in the query string.

For an example that connects mongosh to a replica set using the DNS seed list connection format, see mongosh Connection Options.

Standard Connection String Format

This section describes the standard format of the MongoDB connection URI used to connect to a self-hosted MongoDB standalone deployment, replica set, or sharded cluster.

The standard URI connection scheme has the form:

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

Connection String Database Options

You can specify a default database in the [/defaultauthdb] field of the connection string. The client uses the specified [/defaultauthdb] database as the default database. If unspecified by the connection string, MongoDB uses the test database as the default.

You can specify the authentication database in your connection string using the authSource connection option. If specified, the client uses this database to verify your user identity and credentials. If authSource is unspecified, it defaults to the [/defaultauthdb] database. If both authSource and [/defaultauthdb] are unspecified, authSource defaults to the admin database.

The following example connection string sets the default database to myDefaultDB and the authentication database to admin:

mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/myDefaultDB?authSource=admin