MongoDB connection string format
mongodb://user:password@host1:27017,host2:27017/database?replicaSet=rs0&authSource=adminExamples
| Case | Connection string |
|---|---|
| Local server, no authentication | mongodb://localhost:27017 |
| Local server with a user | mongodb://app:secret@localhost:27017/shop?authSource=admin |
| MongoDB Atlas | mongodb+srv://app:[email protected]/shop?retryWrites=true&w=majority&appName=Shop |
| Replica set | mongodb://app:secret@db1:27017,db2:27017,db3:27017/shop?replicaSet=rs0&authSource=admin |
| Docker (mongo image with MONGO_INITDB_ROOT_USERNAME) | mongodb://root:example@localhost:27017/?authSource=admin |
| Read from secondaries | mongodb://db1,db2,db3/shop?replicaSet=rs0&readPreference=secondaryPreferred |
Every example on this page is checked with MongoDB.Driver itself. Replace the passwords with your own, and keep real ones out of source control.
Special characters in the password
The user name and password are part of a URI, so @ : / ? # [ ] % must be percent-encoded: p@ss:word becomes p%40ss%3Aword. The Build tab does this for you. Without it, the driver reports "The connection string ... is not valid" and hides the credentials in the message.
authSource
The user is looked up in the authSource database. Without it, the driver uses the database in the path, or admin when there is none. Users created with MONGO_INITDB_ROOT_USERNAME in Docker live in admin, so a URI ending in /shop needs authSource=admin. Atlas database users are in admin too.
mongodb+srv
With mongodb+srv:// you give one DNS name without a port. The driver looks up SRV records for the hosts and a TXT record for options, and turns TLS on unless you set tls=false. It cannot be combined with directConnection=true.
What MongoClient checks later
Some strings parse but fail in new MongoClient(...): a user without a password ("A DEFAULT credential must have a password"), readPreferenceTags without readPreference, tags with readPreference=primary, or an unknown authMechanism. The checker reports those too. Unknown options are ignored without an error, so a typo such as retrywrite=false does nothing; the checker lists them.
Where to keep it
Put it under ConnectionStrings in appsettings.json and read it with builder.Configuration.GetConnectionString("Default"). Keep passwords out of the file: user secrets in development, and an environment variable (ConnectionStrings__Default) or a secret store in production.
FAQ
How do I connect to MongoDB from C#?
Install MongoDB.Driver, create one MongoClient with the connection string (it is thread-safe), and call client.GetDatabase("shop"). In ASP.NET Core register it as a singleton.
Why "A DEFAULT credential must have a password"?
The URI has a user name but no password (mongodb://user@host). Add :password, or use an authentication mechanism that needs no password, such as MONGODB-X509.
What is the default port?
27017. mongodb+srv URIs have no port: the SRV record supplies it.
Should I use MongoUrlBuilder.ToString() to rebuild a URI?
Not to round-trip one: in driver 3.12 it drops options such as heartbeatFrequencyMS and unknown options, and writes serverSelectionTimeoutMS=5000 as serverSelectionTimeout=5s. Keep the original string.
Other databases
- PostgreSQL connection string
- SQL Server connection string
- MySQL connection string
- SQLite connection string
- Redis connection string
- Connection string builder for every database