← Connection strings

MongoDB connection strings

Every MongoDB driver, mongosh and Compass take the same URI, which is the good news. The bad news is the three things it hides: which database the user was created in (authSource), what mongodb+srv:// does on its own, and that a password with an @ in it must be percent-encoded or the driver refuses it outright. Below is the URI for the same database, and each option that matters.

Build yours (MongoDB)

The parts of a MongoDB connection string

The shape

mongodb://user:password@host:27017/database?authSource=admin&tls=true
mongodb+srv://
Hosts and port come from DNS (SRV and TXT records); TLS turns on by itself.
user:password@
Must be percent-encoded: : / ? # [ ] @ % — PyMongo raises InvalidURI otherwise.
host:27017
Several hosts for a replica set: h1:27017,h2:27017,h3:27017.
/database
The default database for the client; also the default authSource.
authSource=admin
Where the user was created. Atlas users live in admin.

One MongoDB database, every form

User app_user, password s3cret-Pa55, database shop on db.example.com, tls, verify the certificate.

URI

Every MongoDB driver, mongosh, Compass, Atlas, DATABASE_URL · connected with on a real server

mongodb://app_user:s3cret-Pa55@db.example.com:27017/shop?authSource=admin&tls=true

mongosh command

Shell · connected with on a real server

mongosh 'mongodb://app_user:s3cret-Pa55@db.example.com:27017/shop?authSource=admin&tls=true'

PyMongo

Python · connected with on a real server

MongoClient("mongodb://app_user:s3cret-Pa55@db.example.com:27017/shop?authSource=admin&tls=true")

A password with special characters

The same database with the password p@ss/w#rd 1. URLs encode it, key=value forms quote it, and each form does it differently:

URI

mongodb://app_user:p%40ss%2Fw%23rd%201@db.example.com:27017/shop?authSource=admin&tls=true

mongosh command

mongosh 'mongodb://app_user:p%40ss%2Fw%23rd%201@db.example.com:27017/shop?authSource=admin&tls=true'

PyMongo

MongoClient("mongodb://app_user:p%40ss%2Fw%23rd%201@db.example.com:27017/shop?authSource=admin&tls=true")

CharacterIn a URLWhy it breaks
@%40Ends the user name and password: everything after the first unencoded @ is read as the host.
:%3ASeparates user from password, and host from port.
/%2FStarts the database name.
?%3FStarts the options.
#%23Starts a fragment: the rest of the string is thrown away.
%%25Starts an escape itself, so a literal % must be escaped too.
&%26Separates options.
+%2BSome parsers (PyMongo among them) read + as a space.
space%20Ends the string on a command line, and is trimmed by some parsers.

TLS: what each setting looks like

Shown in the URI form; the builder writes the matching setting for every other one.

No TLS

mongodb://app_user:s3cret-Pa55@db.example.com:27017/shop?authSource=admin

TLS, don't check the certificate

mongodb://app_user:s3cret-Pa55@db.example.com:27017/shop?authSource=admin&tls=true&tlsAllowInvalidCertificates=true

TLS, verify the certificate

mongodb://app_user:s3cret-Pa55@db.example.com:27017/shop?authSource=admin&tls=true

What catches people out on MongoDB

authSource is the usual "Authentication failed"

Without authSource, the driver authenticates against the database in the path. A user created in admin connecting to /shop fails with "Authentication failed" until ?authSource=admin is added.

mongodb+srv:// changes defaults

It looks up the host list in a DNS SRV record, reads options such as replicaSet and authSource from a TXT record, and sets tls=true. No port is allowed after the host name.

One member of a replica set

Given one host of a replica set, the driver discovers the others and connects to the primary — which fails if those member names don't resolve from where you are. directConnection=true talks to the one host you named.

Encoding is not optional

PyMongo, the Node driver and mongosh reject a URI whose user name or password contains an unescaped @, :, / or %. Atlas generates passwords without them for a reason.

Connected. Now what?

Paste the same string into DBShifts to browse MongoDB with sensitive columns masked and every read logged, or to migrate it to another database with each table counted and checksummed afterwards.

Questions

What is the MongoDB connection string format?

mongodb://user:password@host:27017/database?options, or mongodb+srv://user:password@cluster.example.net/database for a DNS seed list (no port). Options include authSource, replicaSet, tls and retryWrites.

How do I fix MongoDB "Authentication failed"?

Most often the user was created in a different database than the one in the URI path: add authSource=admin (or wherever it was created). Otherwise check that special characters in the password are percent-encoded.

What is the difference between mongodb:// and mongodb+srv://?

mongodb:// lists hosts and ports explicitly. mongodb+srv:// gives one DNS name; the driver looks up the hosts in an SRV record and default options in a TXT record, and turns TLS on.

What is the default MongoDB port?

27017.