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")
| Character | In a URL | Why it breaks |
|---|---|---|
| @ | %40 | Ends the user name and password: everything after the first unencoded @ is read as the host. |
| : | %3A | Separates user from password, and host from port. |
| / | %2F | Starts the database name. |
| ? | %3F | Starts the options. |
| # | %23 | Starts a fragment: the rest of the string is thrown away. |
| % | %25 | Starts an escape itself, so a literal % must be escaped too. |
| & | %26 | Separates options. |
| + | %2B | Some parsers (PyMongo among them) read + as a space. |
| space | %20 | Ends 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.
More on MongoDB
Other databases
PostgreSQL connection strings
postgresql://user:password@host:5432/database?sslmode=verify-full
MySQL connection strings
mysql://user:password@host:3306/database
MariaDB connection strings
jdbc:mariadb://host:3306/database?user=…&password=…&sslMode=verify-full
SQL Server connection strings
Server=tcp:host,1433;Database=…;User Id=…;Password=…;Encrypt=True;
Oracle connection strings
host:1521/service_name
SQLite connection strings
sqlite:////var/data/app.db