What MongoDB is & how to run it

This section documents the current MongoDB 8.x server line as published at the MongoDB Server Manual, which is the reference these pages are written and verified against. No specific patch version is pinned. Some capabilities (Atlas Search, Atlas Vector Search, and parts of encryption and backup) are Atlas-only — they are linked, not documented in depth.

This content was generated with the assistance of AI and should be verified against the official manual before being relied on in production, since MongoDB iterates quickly.

This section’s bibliography lists the reference material consulted while preparing these pages.

MongoDB is a general-purpose database that stores records as JSON-like documents rather than as rows in fixed tables. It aims to be a primary datastore for operational applications — the same role a relational database usually fills — while letting the shape of each record vary and letting a deployment scale horizontally across many machines. This page explains the model and its trade-offs, then walks through running a local server and driving it from the shell.

The document model and where it fits

A MongoDB deployment holds one or more databases; each database holds collections; each collection holds documents; each document is a set of field/value pairs. The tiers map cleanly onto the relational vocabulary, with one difference: a collection does not impose a single column list on the documents it holds.

MongoDB database/collection/document/field hierarchy beside the relational database/table/row/column analogy, with each tier mapped to its counterpart

A document that models an order can embed its line items as an array instead of splitting them into a separate table:

{
  "_id": 1001,
  "customer": { "id": 42, "name": "Ada Lovelace" },
  "status": "OPEN",
  "items": [
    { "sku": "A-1", "qty": 2, "price": 9.99 },
    { "sku": "B-7", "qty": 1, "price": 19.00 }
  ]
}

The trade-offs that follow from this model:

  • Flexible schema. Two documents in one collection may carry different fields. Structure is still real — it lives in the application and, optionally, in a JSON Schema validator attached to the collection — but the database does not require you to declare it up front or migrate every record when it changes.

  • Horizontal scale. A collection can be sharded across many servers on a shard key, spreading both data and load. See Sharding.

  • No server-side joins by default. Related data is usually embedded in the same document and read in one operation. Cross-collection joins exist through the $lookup aggregation stage, but they are not the primary access pattern; Data modeling covers embed-versus-reference.

For a narrative overview, see Introduction to MongoDB and the Getting Started tutorial in the manual.

Editions and how you run it

MongoDB ships in three forms:

  • Community Edition — the free, source-available server. Sufficient for development and for most self-managed production use.

  • Enterprise Advanced — Community plus commercial add-ons (in-memory storage engine, Kerberos/LDAP auth, auditing, mongodbtools such as mongodecrypt) and a support subscription.

  • Atlas — MongoDB’s fully managed cloud service. It runs the same server and adds provisioning, backups, monitoring, and Atlas-only features (Atlas Search, Atlas Vector Search) on top. Atlas-only capabilities are linked from these pages, not documented step by step.

See Install MongoDB for packages for each platform.

Start a local mongod

mongod is the database server process. It listens on TCP port 27017 by default and needs a data directory to exist before it starts:

mkdir -p /data/db

# Foreground server, explicit data directory and bind address.
mongod --dbpath /data/db --bind_ip 127.0.0.1 --port 27017

# Equivalent settings in a config file (mongod --config /etc/mongod.conf):
#   https://www.mongodb.com/docs/manual/reference/configuration-options/
# /etc/mongod.conf
storage:
  dbPath: /data/db
net:
  bindIp: 127.0.0.1
  port: 27017

Storage & durability covers the data files --dbpath manages; Administration & monitoring covers running mongod as a managed service.

Connect with mongosh

mongosh is the official shell. With no arguments it connects to mongodb://127.0.0.1:27017:

$ mongosh
test> show dbs
admin   40.00 KiB
config  12.00 KiB
local   40.00 KiB
test> use shop
switched to db shop
shop> db.orders.insertOne({ _id: 1001, status: "OPEN" })
{ acknowledged: true, insertedId: 1001 }
shop> show collections
orders
shop> db.orders.find()
[ { _id: 1001, status: 'OPEN' } ]

show dbs lists databases, use <db> selects one (and creates it lazily on first write), show collections lists its collections, and db.<coll>.find() reads documents. Full command reference: the mongosh documentation. The db.<coll>.find() / insertOne() calls are the Query API, covered in Querying documents and Inserting documents.

mongosh is a JavaScript REPL

mongosh evaluates JavaScript. Query results are ordinary values you can assign and manipulate, and a find() returns a cursor:

// Assign a result and work with it as a normal object.
const order = db.orders.findOne({ _id: 1001 })
order.status                       // 'OPEN'

// find() returns a cursor; the shell prints the first batch (20 docs) and
// leaves the cursor open. Type `it` to page through the rest.
db.orders.find({ status: "OPEN" })
// Type:  it        -> next batch

// Drive the cursor explicitly instead of relying on `it`.
db.orders.find().forEach(doc => print(doc._id))

// Cursor helpers: https://www.mongodb.com/docs/manual/reference/method/js-cursor/
db.orders.find().sort({ _id: -1 }).limit(5).toArray()

Startup and scripting:

# ~/.mongoshrc.js runs on every interactive start -- put helpers and prompt
# tweaks there. https://www.mongodb.com/docs/mongodb-shell/reference/startup/
echo 'prompt = () => `${db.getName()}> `;' >> ~/.mongoshrc.js

# Run a script file non-interactively (exits when the file finishes).
mongosh "mongodb://127.0.0.1:27017/shop" seed.js

# Or load a file into the current interactive session.
#   shop> load("seed.js")

mongosh replaces the legacy mongo shell, which is no longer shipped with the server.

What MongoDB is not

  • Not a cache. It persists to disk with journaling and configurable write concern; it is a system of record, not a volatile key/value layer in front of one.

  • Not "schemaless" in the sense of having no rules. Every document must be valid BSON under the 16 MB size limit, _id is always unique within its collection, index key constraints still apply, and a collection can enforce a schema validator. What is flexible is that the schema is not declared centrally, not that anything goes.

  • Not a drop-in SQL replacement. There is no JOIN as the default access path, no cross-document foreign keys, and multi-document transactions — while supported, see Transactions — are a deliberate choice rather than the norm. Porting a normalized relational schema unchanged usually works against the model.

For the relational baseline these points contrast with, see SQL Reference. Continue with Documents, BSON & data types.