MongoDB connection string: mongodb:// and mongodb+srv:// explained

The two formats

mongodb://[user:password@]host1[:port1][,host2[:port2],...][/[defaultauthdb][?options]]
mongodb+srv://[user:password@]host[/[defaultauthdb][?options]]

Tested with mongosh 2.12.0 against MongoDB 8.0:

mongosh 'mongodb://root:<password>@localhost:27017/inlet?authSource=admin&appName=orders-api' \
  --eval 'db.getName()'

inlet

Without a database in the path, mongosh starts in test.

mongodb+srv: hosts from DNS

With mongodb+srv://cluster0.example.net/, the driver doesn’t connect to cluster0.example.net. It looks up two DNS records:

• an SRV record at _mongodb._tcp.cluster0.example.net, listing each server’s host name and port;
• a TXT record at cluster0.example.net, which may add the options replicaSet and authSource.

MongoDB’s documentation shows records like these:

_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.
server.example.com.               86400 IN TXT "replicaSet=mySet&authSource=authDB"

You can see your own cluster’s records with dig:

dig +short SRV _mongodb._tcp.<cluster host>
dig +short TXT <cluster host>

What +srv implies:

• TLS is on (tls=true) unless the string says tls=false.
• One host name, no port. mongosh rejects anything else before looking anything up:

  MongoParseError: mongodb+srv URI cannot have port number
  MongoParseError: mongodb+srv URI cannot have multiple service names
  

• The servers must be in the same parent domain as the name you gave (*.example.net for cluster0.example.net), or the driver refuses them.
• You can move servers without changing the string. The DNS records change instead.
• DNS must work from where you are. A lookup failure looks like Error: querySrv ENOTFOUND _mongodb._tcp.cluster0.example.net. If your network’s DNS server doesn’t answer SRV queries, use the provider’s standard mongodb:// string, which lists every host and needs no lookup.

Options

authSource

The database where the user was created, which is where MongoDB checks the password. If you don’t set it, the driver uses the database in the path, or admin if there isn’t one. Users created in admin (as on most hosted services) need authSource=admin when the path names another database:

mongodb://root:…@localhost:27017/inlet                    → MongoServerError: Authentication failed.
mongodb://root:…@localhost:27017/inlet?authSource=admin   → connected

That’s the most common cause of MongoDB authentication failed. For mongodb+srv strings, the TXT record often sets authSource=admin for you.

authMechanism

How to sign in. Without it, drivers agree on SCRAM-SHA-256 or SCRAM-SHA-1 with the server, which is what you want for passwords. A user stored with SCRAM-SHA-1 only connected with no authMechanism, and failed when we forced SCRAM-SHA-256:

MongoServerError: Unable to use SCRAM-SHA-256 based authentication for user without any SCRAM-SHA-256 credentials registered

Other values: MONGODB-X509 (client certificate), MONGODB-AWS (IAM), GSSAPI (Kerberos), PLAIN (LDAP), MONGODB-OIDC. These authenticate against $external rather than a database: authSource=$external. A mechanism the server doesn’t have fails at once:

MongoServerError: Received authentication for mechanism PLAIN which is not enabled

replicaSet

The replica set’s name. With it, the driver treats the hosts as a seed list, discovers the other members and sends writes to whichever is primary. If the name is wrong, or the server isn’t a replica set member, server selection times out. Against a standalone server:

MongoServerSelectionError: Server selection timed out after 2000 ms

directConnection

directConnection=true talks only to the host you named, without discovering the rest of a replica set. Use it to reach one specific member (say, a secondary for a slow report), or a member through an SSH tunnel or port-forward whose real address isn’t reachable from your machine. The default is false. mongosh adds directConnection=true by itself when you give it a single host and no replicaSet; its db.getMongo()._uri showed:

mongodb://root:…@localhost:27017/seo_strings?authSource=admin&appName=orders-api&directConnection=true&serverSelectionTimeoutMS=2000

retryWrites

Retry a write once if it fails with a network error or a primary change. Official drivers default to true, and Atlas strings usually include it. Retryable writes need a replica set or sharded cluster; on a standalone server the setting changes nothing.

w

The write concern: how many members must confirm a write before it counts as done.

• w=majority: most voting members. Since MongoDB 5.0 it’s the default for most deployments.
• w=1: the primary only.
• w=0: don’t wait at all. The driver can’t report errors:

  { acknowledged: false, insertedId: ObjectId('6ac8bdb45c59925b1ef7d1b4') }
  

• A number larger than the members you have can never be satisfied. On a standalone:

  MongoServerError: cannot use 'w' > 1 when a host is not replicated
  

wtimeoutMS limits how long to wait for the write concern (deprecated in newer drivers in favour of timeoutMS), and journal=true waits for the journal.

appName

A label that shows up in the server’s logs, in db.currentOp() and in the profiler. Set it per service, so you can tell your API from a batch job. With appName=orders-api, our session’s currentOp entry had appName: 'orders-api'.

TLS and timeouts

• tls=true: encrypt (on by default with +srv). tlsCAFile=<path> trusts a specific CA, such as your own or a cloud provider’s. tlsAllowInvalidCertificates=true turns off certificate checks: for a throwaway test only.
• serverSelectionTimeoutMS: how long to look for a suitable server before giving up (default 30,000 ms). connectTimeoutMS: per connection attempt (default 10,000 ms).
• readPreference=secondaryPreferred and friends: where reads go.

Examples

# Local, no authentication
mongodb://localhost:27017/shop

# Local, user created in admin
mongodb://app:<password>@localhost:27017/shop?authSource=admin

# Self-hosted replica set
mongodb://app:<password>@db1.example.com:27017,db2.example.com:27017,db3.example.com:27017/shop?replicaSet=rs0&authSource=admin&tls=true&appName=orders-api

# Atlas (TLS, hosts and authSource from DNS)
mongodb+srv://app:<password>@cluster0.<id>.mongodb.net/shop?retryWrites=true&w=majority&appName=orders-api

In Inlet

Paste a mongodb:// or mongodb+srv:// URL into a new connection and Inlet fills in the form; the password goes in the Keychain. Collections show as tables, documents open in the inspector, and you write queries in mongosh syntax (db.users.find({…})). For Atlas specifics, see Connect to MongoDB Atlas.