Docs Menu
Docs Home
/
MongoDB Manual
/
Reference

Connection Strings

On this page

  • Compatibility
  • Find Your MongoDB Atlas Connection String
  • Find Your Self-Hosted Deployment's Connection String
  • Connection String Formats
  • SRV Connection Format
  • Standard Connection String Format

➤ Use the Select your language drop-down menu in the upper-right to set the language of the following examples.

You can use connection strings to define connections between MongoDB instances and the following destinations:

  • Your applications when you connect using drivers.

  • Tools such as MongoDB Compass and the MongoDB Shell (mongosh).

Compatibility

You can use connection strings to connect to deployments hosted in the following environments:

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

  • MongoDB Enterprise: The subscription-based, self-managed version of MongoDB

  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Complete these steps to find your connection string.

Find Your MongoDB Atlas Connection String

To find your MongoDB Atlas connection string using the Atlas CLI, install and connect from the Atlas CLI, then run the following command. Replace <clusterName> with the name of the MongoDB Atlas cluster and replace <projectId> with the project ID.

atlas clusters connectionStrings describe <clusterName> --projectId <projectId>

To learn more, see atlas clusters connectionStrings describe.

To find your MongoDB Atlas connection string in the Atlas UI, follow these steps:

1

In the MongoDB Atlas UI, go to the Clusters page for your project.

  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your project from the Projects menu in the navigation bar.

  3. If it's not already displayed, click Clusters in the sidebar.

    The Clusters page displays.

2

Open the Connection Method dialog.

  1. Click Connect for the cluster to which you want to connect.

  2. Click Choose a Connection Method. MongoDB Atlas selects Standard Connection by default. To connect using a private endpoint, select Private Endpoint.

3

Choose a connection method.

To connect to your application, click Drivers. To connect using tools, click the tool you want to use to access your data.

4

Follow instructions for the connection method you selected.

  1. If you selected Drivers, select your driver and version. If you selected a tool, download the tool.

  2. Select Connect To Cluster.

  3. Copy the connection string. Replace <password> and <username> in the connection string with the database user's credentials.

Your MongoDB Atlas connection string resembles the following example:

mongosh "mongodb+srv://cluster0.example.mongodb.net myFirstDatabase" --apiVersion 1 --username myDatabaseUser
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?retryWrites=true&w=majority
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?retryWrites=true&w=majority
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?retryWrites=true&w=majority
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?retryWrites=true&w=majority
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?retryWrites=true&w=majority
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?retryWrites=true&w=majority
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?retryWrites=true&w=majority
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?retryWrites=true&w=majority

Find Your Self-Hosted Deployment's Connection String

If you are connected to your self-hosted MongoDB Enterprise or MongoDB Community deployment, run db.getMongo() method to return the connection string.

If you are not connected to your deployment, you can determine your connection string based on the connection type you want to use. See SRV Connection Format to learn the SRV connection string syntax or Standard Connection String Format to learn the standard connection string syntax.

Your self-hosted connection string resembles the following examples:

The following replica set connection string includes these elements:

  • The replicaSet option

  • The hostname(s) of the mongod instance(s) as listed in the replica set configuration

  • It authenticates as user myDatabaseUser with the password D1fficultP%40ssw0rd to enforce access control

mongosh "mongodb+srv://mongodb0.example.com/?authSource=admin&replicaSet=myRepl" --apiVersion 1 --username myDatabaseUser
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin&replicaSet=myRepl
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin&replicaSet=myRepl
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin&replicaSet=myRepl
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin&replicaSet=myRepl
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin&replicaSet=myRepl
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin&replicaSet=myRepl
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin&replicaSet=myRepl
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin&replicaSet=myRepl
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin&replicaSet=myRepl
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin&replicaSet=myRepl
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin&replicaSet=myRepl
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin&replicaSet=myRepl

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

$ : / ? # [ ] @

The following sharded cluster connection string includes the these elements:

  • The mongos hosts in the connection string

  • It authenticates as user myDatabaseUser with the password D1fficultP%40ssw0rd to enforce access control

mongosh "mongodb+srv://mongos0.example.com/?authSource=admin" --apiVersion 1 --username myDatabaseUser
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin

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

$ : / ? # [ ] @

The following standalone connection string authenticates as user myDatabaseUser with the password D1fficultP%40ssw0rd to enforce access control:

mongosh "mongodb+srv://mongodb0.example.com/?authSource=admin" --apiVersion 1 --username myDatabaseUser
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/?authSource=admin

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

$ : / ? # [ ] @

The following replica set connection string includes these elements:

mongosh "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl" --apiVersion 1 --username myDatabaseUser
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl

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

$ : / ? # [ ] @

The following sharded cluster connection string includes the these elements:

mongosh "mongodb://mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin" --apiVersion 1 --username myDatabaseUser
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin

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

$ : / ? # [ ] @

The following standalone connection string enforces access control:

mongosh "mongodb://@mongodb0.example.com:27017/?authSource=admin" --apiVersion 1 --username myDatabaseUser
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin
mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/?authSource=admin

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

$ : / ? # [ ] @

For a full list of connection string options, see SRV Connection Format or Standard Connection String Format. For more examples, see Connection String Examples.

Connection String Formats

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

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

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 Connection String Examples.

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:

$ : / ? # [ ] @

See also authSource.

host[:port]

The host (and optional port number) where the mongod instance (or mongos instance for a sharded cluster) is running. You can specify a hostname, IP address, or UNIX domain socket. Specify as many hosts as appropriate for your deployment topology:

  • For a standalone, specify the hostname of the standalone mongod instance.

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

  • For a sharded cluster, specify the hostname(s) of the mongos instance(s).

If the port number is not specified, the default port 27017 is used.

If you use the SRV URI connection format, you can specify only one host and no port. Otherwise, the driver or mongosh raises a parse error and does not perform DNS resolution.

/defaultauthdb

Optional. The authentication database to use if the connection string includes username:password@ authentication credentials but the authSource option is unspecified.

If both authSource and defaultauthdb are unspecified, the client will attempt to authenticate the specified user to the admin database.

?<options>

Optional. A query string that specifies connection specific options as <name>=<value> pairs. 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 (/) between the last host and the question mark (?) that begins the string of options.

In order to leverage the DNS seed list, use the same syntax as a standard connection string with a prefix of mongodb+srv rather than the standard mongodb. The +srv indicates to the client that the hostname that follows corresponds to a DNS SRV record. The driver or mongosh will then query the DNS for the record to determine which hosts are running the mongod or mongos instances.

Note

Use of the +srv connection string modifier automatically sets the tls (or the equivalent ssl) option 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.

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 will 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 will not be able to connect.

This example shows a DNS seed list connection string that is missing the <hostname>. This is incorrect and raises an error.

# This connection string is missing the <hostname> and raises a connection error
mongodb+srv://myDatabaseUser:D1fficultP%[email protected]/

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 may only specify one TXT record per mongod instance. If multiple TXT records appear in the DNS and/or if the TXT record 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 TXT record resolve to the following standard format connection string:

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

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

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

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]]

For more examples, see Connection String Examples.

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:

$ : / ? # [ ] @

See also authSource.

host[:port]

The host (and optional port number) where the mongod instance (or mongos instance for a sharded cluster) is running. You can specify a hostname, IP address, or UNIX domain socket. Specify as many hosts as appropriate for your deployment topology:

  • For a standalone, specify the hostname of the standalone mongod instance.

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

  • For a sharded cluster, specify the hostname(s) of the mongos instance(s).

If the port number is not specified, the default port 27017 is used.

If you use the SRV URI connection format, you can specify only one host and no port. Otherwise, the driver or mongosh raises a parse error and does not perform DNS resolution.

/defaultauthdb

Optional. The authentication database to use if the connection string includes username:password@ authentication credentials but the authSource option is unspecified.

If both authSource and defaultauthdb are unspecified, the client will attempt to authenticate the specified user to the admin database.

?<options>

Optional. A query string that specifies connection specific options as <name>=<value> pairs. 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 (/) between the last host and the question mark (?) that begins the string of options.

Back

Locales & Default Parameters

Next

Options