MongoDB connection strings use a different format than MySQL or PostgreSQL

MongoDB stores your credentials directly in the connection string itself, rather than asking for them separately when you connect. The format looks like this: mongodb://username:password@hostname:port/database. You replace those placeholders with your actual MongoDB username, password, the server address, the port number (usually 27017), and the database name you want to access.

The key difference from relational databases is that MongoDB expects the credentials to be part of the connection URL from the start. If you're coming from MySQL or PostgreSQL, where you might pass credentials as separate parameters, this takes some adjustment. But once you have the pieces in place, the connection works the same way — you're just formatting them differently.

Key Takeaways

  • MongoDB connection strings embed the username and password directly in the URL as mongodb://username:password@hostname:port/database.
  • Special characters in your password (like @ or :) must be URL-encoded, or the connection string will fail to parse correctly.
  • The default MongoDB port is 27017, but your hosting provider or local setup may use a different port — check your configuration.
  • Most MongoDB clients (MongoDB Compass, the mongo shell, drivers in Python or Node.js) accept the connection string as a single parameter.

Where to find your MongoDB username and password

If you're using MongoDB Atlas (the cloud-hosted version), log into your Atlas account and go to the Database Access section. You'll see a list of database users you've created. If you haven't created one yet, click "Add New Database User" and set a username and password there. Write down both — you'll need them for the connection string.

If you're running MongoDB on your own server or local machine, the username and password depend on how you set it up. If you created a user during installation, use those credentials. If you're not sure, check your MongoDB configuration file (usually mongod.conf on Linux or macOS, or in the MongoDB installation folder on Windows) or the documentation for how you installed it.

Building the connection string step by step

Start with the protocol: mongodb://. Then add your username, a colon, and your password: mongodb://myuser:mypassword. Next comes the @ symbol, then the hostname (the server address where MongoDB is running). If you're connecting to Atlas, this looks like cluster0.abc123.mongodb.net. If it's local, use localhost.

After the hostname, add a colon and the port number: mongodb://myuser:mypassword@localhost:27017. Finally, add a forward slash and the database name: mongodb://myuser:mypassword@localhost:27017/mydatabase. That's your complete connection string.

If your password contains special characters like @ or :, you must URL-encode them first. For example, if your password is pass@word, replace the @ with %40 so it reads pass%40word in the connection string. Common encodings: @ becomes %40, : becomes %3A, / becomes %2F, # becomes %23. Many online URL encoders can do this for you.

Connecting with MongoDB Compass (the graphical client)

Open MongoDB Compass and look for the connection field at the top. Paste your full connection string there and click "Connect". Compass will parse the string, extract the credentials, and attempt to connect to your MongoDB server. If the connection succeeds, you'll see your databases listed on the left side.

If the connection fails, Compass will show an error message. Common reasons: the username or password is wrong, the hostname is unreachable, the port is blocked by a firewall, or special characters in the password weren't URL-encoded. Double-check each part of the string against what you have in your MongoDB account or configuration.

Connecting from the command line (mongo shell)

Open a terminal or command prompt and type: mongosh "mongodb://myuser:mypassword@localhost:27017/mydatabase". Replace the placeholders with your actual credentials and server details. The mongosh command is the newer MongoDB shell; older versions use mongo instead, but the syntax is the same.

If you're on Windows and mongosh isn't recognized as a command, you may need to add MongoDB to your system PATH, or navigate to the folder where MongoDB is installed first. On macOS or Linux, if you installed MongoDB via a package manager, mongosh should be available from anywhere.

Connecting from code (Python, Node.js, and other drivers)

Each programming language has a MongoDB driver that accepts the connection string. In Python with PyMongo, you'd write:

from pymongo import MongoClient client = MongoClient("mongodb://myuser:mypassword@localhost:27017/mydatabase") db = client.mydatabase

In Node.js with the MongoDB driver, it looks like:

const { MongoClient } = require("mongodb"); const client = new MongoClient("mongodb://myuser:mypassword@localhost:27017/mydatabase"); client.connect();

In both cases, you pass the connection string as a parameter to the client constructor. The driver handles parsing the credentials and connecting to the server. Once connected, you can query your database using the driver's methods.

Troubleshooting connection failures

If your connection fails, work through these checks in order. First, verify the username and password are correct by logging into your MongoDB account (Atlas) or checking your local configuration. Second, confirm the hostname is reachable — if you're using Atlas, make sure your IP address is whitelisted in the Network Access section. Third, check that the port is correct and not blocked by a firewall.

Fourth, if your password contains special characters, make sure they're URL-encoded in the connection string. Fifth, try removing the database name from the end of the string and connecting to the server first — sometimes the database doesn't exist yet, and that can cause the connection to fail. Finally, check the error message carefully; MongoDB drivers usually tell you whether the problem is authentication, network connectivity, or something else.

Frequently Asked Questions

What if I don't know my MongoDB password?

In MongoDB Atlas, go to Database Access, find your user, and click the "Edit" button. You can reset the password there. For a local MongoDB installation, you'll need to stop the server, restart it without authentication, create a new user, and restart it again with authentication enabled. Check your MongoDB documentation for the exact steps for your operating system.

Can I use the same connection string on multiple machines?

Yes, as long as each machine can reach the hostname and port in the string. If you're using Atlas, the connection string works from anywhere (as long as your IP is whitelisted). If MongoDB is on a local network or private server, only machines on that network can connect. Never share a connection string that contains a password in plain text — treat it like a password itself.

What does "authentication failed" mean?

It means MongoDB rejected your username or password. Double-check both are spelled correctly and that you're connecting to the right database. In Atlas, make sure the user exists in the Database Access section. For local installations, verify the user was created with the correct password before authentication was enabled.

Do I have to include the database name in the connection string?

No. You can connect without specifying a database — mongodb://myuser:mypassword@localhost:27017 will work. You'll then select which database to use after connecting. Including the database name is optional but useful if you always work with the same one.

Why does my password with an @ symbol keep failing?

The @ symbol has special meaning in connection strings — it separates credentials from the hostname. If your password contains @, you must replace it with %40 so MongoDB doesn't misinterpret where the credentials end. The same applies to other special characters like : (colon) and / (forward slash).