Installing MongoDB & Setup

Server, Shell, Driver — Three Different Things

Before installing anything, get the pieces straight, because mixing them up is the single most common reason a beginner's first hour with MongoDB goes badly.

The server is the program that actually stores your data. Its executable is called mongod (the d is for daemon, a background program). The shell is mongosh — a separate command-line program you type queries into, which connects to a server over the network. The driver is a library you install in your project, such as the mongodb package for Node.js, so your application code can talk to the same server.

So mongosh on its own stores nothing. If nobody is running a server, the shell has nothing to connect to. That is what the error connect ECONNREFUSED 127.0.0.1:27017 means: the shell reached out to port 27017 on your own machine and found no server listening there.

• mongod — the database server, listens on port 27017 by default
• mongosh — the interactive shell you type commands into
• mongodb (npm package) — the official Node.js driver your app uses
• MongoDB Compass — an optional desktop app that shows your data in a window

Option 1: MongoDB Atlas, the Cloud Route

Atlas is MongoDB's own hosted service. You do not install a server at all — MongoDB runs one for you and gives you an address to connect to. There is a free tier (called M0) with 512 MB of storage, which is more than enough for every exercise in this course and for a college project. For most learners this is the route to take, because it removes an entire class of installation problems and because the free cluster is a three-node replica set, which means transactions work on it.

The setup is four steps in the Atlas web dashboard: create an account, create a free cluster, create a database user (a username and password that belong to the database, not to your Atlas login), and add your current IP address under Network Access. Then copy the connection string and open it in mongosh.

Two things trip up almost everybody here. First, the connection string you copy contains a literal <password> placeholder — you must replace it, angle brackets and all. Second, if your password contains characters like @, :, / or #, they must be percent-encoded, because those characters already have a meaning inside a URL. An @ in a password must be written as %40. If you would rather not think about it, generate a password made only of letters and digits.

# Install just the shell (the server lives in the cloud)
# macOS
brew install mongosh
# Windows: download the mongosh MSI from mongodb.com/try/download/shell

# Connect to your Atlas cluster
mongosh "mongodb+srv://cluster0.abcde.mongodb.net/" --username appuser
# you will be prompted for the password

# Check it worked
db.runCommand({ ping: 1 })
// { ok: 1 }

Option 2: Installing MongoDB on Your Own Machine

A local install is worth having too. It works without internet, it is fast, and you can wipe it and start again without worrying. Install MongoDB Community Server — the free edition — from the official downloads page for your operating system, and install mongosh alongside it.

On Windows the installer is an MSI that can register MongoDB as a Windows service, which means the server starts by itself whenever you boot. On macOS, Homebrew is the easiest path. On Linux, use the repository MongoDB publishes for your distribution rather than whatever package your distro ships under the name mongodb; those distro packages are frequently several major versions behind and may not exist at all on newer releases.

Whichever route you take, finish by checking two things: that mongosh --version prints a version, and that connecting with a bare mongosh succeeds. If the version prints but the connection is refused, the shell is installed and the server is not running — start the service and try again.

# macOS (Homebrew)
brew tap mongodb/brew
brew install mongodb-community@7.0
brew services start mongodb-community@7.0

# Windows (PowerShell, after installing as a service)
net start MongoDB

# Linux (systemd), after installing from MongoDB's official repository
sudo systemctl start mongod
sudo systemctl enable mongod    # start on every boot
sudo systemctl status mongod    # should say: active (running)

# Verify from any OS
mongosh --version
mongosh                          # connects to mongodb://127.0.0.1:27017

mongosh Is a JavaScript Shell

mongosh is not a limited command prompt with a few fixed commands. It is a full JavaScript environment with a database connection attached. Anything valid in Node.js is valid here: you can declare variables with const, write for loops, define functions, and use template strings. That is why it is such a good place to learn — you can generate a hundred test documents in three lines instead of typing them out.

The special-looking words are only a small set. show dbs lists databases, use <name> switches to one, show collections lists the collections in the current database, and the variable db always points at whichever database you last switched to. Everything else is a normal method call on db or on a collection.

// Housekeeping commands
show dbs                 // list databases on this server
use shopDB               // switch to shopDB (creates it lazily)
show collections         // list collections in shopDB
db                       // prints the current database name
db.stats()               // size, collection count, index count
exit                     // leave the shell

// It really is JavaScript — generate 50 test products in one go
const docs = []
for (let i = 1; i <= 50; i++) {
  docs.push({ name: `Product ${i}`, price: i * 100, inStock: i % 3 !== 0 })
}
db.products.insertMany(docs)

db.products.countDocuments()   // 50

Your First Five Minutes: A Walkthrough

Run the sequence below line by line and read what comes back. It is the whole shape of this course in miniature: pick a database, insert something, read it back, change it, and count what is there.

The one surprise is at the start. After use shopDB, running show dbs will not list shopDB. MongoDB creates a database only when the first piece of data is actually written to it, so an empty database does not exist yet as far as the server is concerned. Insert one document and it appears. This is not a bug, and it catches nearly every beginner once.

use shopDB

db.products.insertOne({ name: "Wireless Mouse", price: 799, brand: "Logi" })
// { acknowledged: true, insertedId: ObjectId("...") }

db.products.find()
// [ { _id: ObjectId("..."), name: 'Wireless Mouse', price: 799, brand: 'Logi' } ]

db.products.updateOne(
  { name: "Wireless Mouse" },
  { $set: { price: 749 } }
)
// { matchedCount: 1, modifiedCount: 1, ... }

db.products.countDocuments()   // 1

show dbs                        // shopDB now appears in the list