MongoDB

MongoDB with Node.js: The Complete Guide 🍃

1. Introduction 🌱

MongoDB is a document-oriented, NoSQL database that stores data as flexible, JSON-like documents instead of rigid rows and columns. When paired with Node.js, it becomes one of the most popular stacks for building scalable, modern web applications — commonly referred to as part of the MERN/MEAN stack.

In this tutorial, you will learn how to connect to MongoDB from a Node.js application, perform CRUD operations, work with aggregation pipelines, handle transactions, and apply production-grade best practices.

Information

This tutorial assumes basic familiarity with JavaScript, Node.js, and command-line tools. No prior MongoDB experience is required.

Why MongoDB with Node.js? 🤔

Both MongoDB and Node.js speak JSON/BSON natively, which removes the need for an ORM translation layer that relational databases typically require. This makes the developer experience seamless.

Schema flexibility— documents in the same collection can have different fields.
JSON-native— data maps directly to JavaScript objects.
Horizontal scalability— built-in sharding support.
Rich querying— powerful aggregation framework.

2. MongoDB Node.js Driver 🚗

The official mongodb package is the low-level driver maintained by MongoDB Inc. It provides direct access to the database without any additional abstraction layer, unlike Mongoose, which is an ODM built on top of it.

Native Driver

Mongoose (ODM)

The mongodb package gives you full control and closely mirrors the shell API. Install it with:

terminal

npm install mongodb

Mongoose adds schemas, validation, and middleware/hooks on top of the native driver, at the cost of some flexibility and a slight performance overhead.

terminal

npm install mongoose

Tip

This tutorial focuses primarily on the native driver since it teaches the underlying concepts that Mongoose itself relies on.

3. Connecting to MongoDB 🔌

Connecting involves creating a MongoClient instance, calling connect(), and obtaining a reference to your target database.

📦

Install the driver via npm install mongodb.

🔑

Build a connection string (URI).

🔌

Instantiate MongoClient and call connect().

🗄️

Access a Db instance via client.db().

📁

Access a Collection instance via db.collection().

connect.js

const { MongoClient } = require('mongodb');

const uri = 'mongodb://127.0.0.1:27017';
const client = new MongoClient(uri);

async function main() {
  await client.connect();
  console.log('Connected successfully! 🎉');
  const db = client.db('shopDB');
  return db;
}

main().catch(console.error);

4. Connection Strings 🔗

A MongoDB connection string (URI) encodes host, port, credentials, database name, and options in a single string.

Format	Example	Use Case
Standard	mongodb://host:port/db	Local or single-node deployments
SRV	mongodb+srv://cluster.mongodb.net	MongoDB Atlas / replica sets

.env

MONGO_URI=mongodb+srv://<username>:<password>@cluster0.mongodb.net/shopDB?retryWrites=true&w=majority

Warning

Never hard-code credentials directly in source code. Always load them from environment variables (see Section 18).

Common URI Options ⚙️

retryWrites=true— automatically retries failed write operations.
w=majority— write concern requiring acknowledgment from a majority of replica set members.
maxPoolSize— controls the connection pool size (see Section 17).

5. MongoClient 🧭

The MongoClient class manages the underlying connection pool and is designed to be instantiated once and reused throughout your application's lifetime.

client.js

const { MongoClient } = require('mongodb');

const client = new MongoClient(process.env.MONGO_URI, {
  maxPoolSize: 10,
});

async function connectDB() {
  try {
    await client.connect();
    await client.db('admin').command({ ping: 1 });
    console.log('Pinged your deployment. Connection successful! ✅');
  } catch (err) {
    console.error('Connection failed ❌', err);
  }
}

module.exports = { client, connectDB };

Important

Calling client.connect() multiple times is unnecessaryand wasteful — the driver already manages pooled connections internally after the first call.

6. Database Instances 🗄️

Once connected, use client.db(name) to obtain a Db object, which acts as an entry point to all collections within that database.

db-instance.js

const db = client.db('shopDB');

// List all collections in this database
const collections = await db.listCollections().toArray();
console.log(collections.map(c => c.name));

If the database name is omitted, it defaults to the one specified in the connection string.
Databases are created lazily— they only persist once data is written to them.

7. Collection Instances 📁

A collection is analogous to a table in relational databases, but without an enforced schema. Access one via db.collection(name).

collection-instance.js

const usersCollection = db.collection('users');

// Create with explicit validation rules
await db.createCollection('orders', {
  validator: {
    $jsonSchema: {
      bsonType: 'object',
      required: ['itemName', 'quantity'],
      properties: {
        itemName: { bsonType: 'string' },
        quantity: { bsonType: 'int', minimum: 1 },
      },
    },
  },
});

Note

Like databases, collections are also created lazily upon the first insert unless explicitly created with options like validators.

8. CRUD Operations 🛠️

CRUD stands for Create, Read, Update, Delete— the four fundamental operations for interacting with data.

Create ➕

create.js

// Insert a single document
const result = await usersCollection.insertOne({
  name: 'Alice',
  email: 'alice@example.com',
  age: 28,
});
console.log('Inserted ID:', result.insertedId);

// Insert multiple documents
await usersCollection.insertMany([
  { name: 'Bob', age: 34 },
  { name: 'Carol', age: 25 },
]);

Read 👀

read.js

const user = await usersCollection.findOne({ name: 'Alice' });
const allUsers = await usersCollection.find({}).toArray();

Update ✏️

update.js

await usersCollection.updateOne(
  { name: 'Alice' },
  { $set: { age: 29 } }
);

await usersCollection.updateMany(
  { age: { $lt: 30 } },
  { $inc: { age: 1 } }
);

Delete 🗑️

delete.js

await usersCollection.deleteOne({ name: 'Bob' });
await usersCollection.deleteMany({ age: { $gt: 60 } });

Operation	Single Document	Multiple Documents
Create	insertOne	insertMany
Update	updateOne	updateMany
Delete	deleteOne	deleteMany

9. Querying Documents 🔍

MongoDB's query language uses operators prefixed with $ to build expressive filters.

Comparison Operators

query-comparison.js

// Find users older than 25 and younger than 40
const results = await usersCollection.find({
  age: { $gt: 25, $lt: 40 },
}).toArray();

Logical Operators

query-logical.js

const results = await usersCollection.find({
  $or: [{ name: 'Alice' }, { name: 'Carol' }],
}).toArray();

Projection, Sorting & Pagination

query-advanced.js

const results = await usersCollection
  .find({}, { projection: { name: 1, email: 1, _id: 0 } })
  .sort({ age: -1 })
  .skip(10)
  .limit(5)
  .toArray();

Best Practice

Always add an index on fields you frequently query or sort by to avoid full collection scans.

10. Aggregation 📊

The aggregation pipeline processes documents through a sequence of stages, each transforming the data — similar to a Unix pipe.

$match

$group

$sort

$project

aggregation.js

const results = await db.collection('orders').aggregate([
  { $match: { status: 'completed' } },
  { $group: { _id: '$customerId', total: { $sum: '$amount' } } },
  { $sort: { total: -1 } },
  { $limit: 10 },
]).toArray();

$match— filters documents (like a query).
$group— groups documents and computes aggregates.
$project— reshapes documents, including/excluding fields.
$lookup— performs a left outer join with another collection.

11. Transactions 🔒

Transactions allow multiple operations across one or more documents/collections to execute atomically— either all succeed or all are rolled back.

transactions.js

const session = client.startSession();

try {
  await session.withTransaction(async () => {
    const accounts = db.collection('accounts');
    await accounts.updateOne(
      { _id: 'A' }, { $inc: { balance: -100 } }, { session }
    );
    await accounts.updateOne(
      { _id: 'B' }, { $inc: { balance: 100 } }, { session }
    );
  });
  console.log('Transaction committed successfully ✅');
} finally {
  await session.endSession();
}

Caution

Transactions require a replica set or sharded cluster— they are not supported on standalone instances.

12. Sessions 🎫

A ClientSession tracks a logical sequence of operations that need to be causally related — required for transactions, and useful for causal consistency.

sessions.js

const session = client.startSession({
  defaultTransactionOptions: {
    readConcern: { level: 'snapshot' },
    writeConcern: { w: 'majority' },
  },
});

// Always end sessions when done
await session.endSession();

Reference

Sessions are lightweight but must be explicitly ended to free server-side resources.

13. Bulk Operations 📦

When performing many writes, bulkWrite() batches operations into a single round-trip, significantly improving throughput.

bulk-operations.js

const result = await usersCollection.bulkWrite([
  { insertOne: { document: { name: 'Dave', age: 40 } } },
  { updateOne: { filter: { name: 'Alice' }, update: { $set: { age: 30 } } } },
  { deleteOne: { filter: { name: 'Bob' } } },
]);

console.log(`Inserted: ${result.insertedCount}, Modified: ${result.modifiedCount}`);

Tip

Use the ordered: false option to allow independent operations to continue executing even if one fails.

14. Change Streams 📡

Change streams let your application react in real time to data changes, without polling, by tailing the replication oplog.

change-streams.js

const changeStream = usersCollection.watch();

changeStream.on('change', (change) => {
  console.log('Change detected 🔔:', change.operationType);
});

// Filter for specific operation types
const pipeline = [{ $match: { operationType: 'insert' } }];
const insertStream = usersCollection.watch(pipeline);

Information

Change streams also require a replica set or sharded cluster, just like transactions.

15. GridFS 🖼️

GridFS is a specification for storing and retrieving files that exceed the 16MB document size limit, by splitting them into chunks.

gridfs.js

const { GridFSBucket } = require('mongodb');
const fs = require('fs');

const bucket = new GridFSBucket(db, { bucketName: 'uploads' });

// Upload a file
fs.createReadStream('./photo.jpg')
  .pipe(bucket.openUploadStream('photo.jpg'))
  .on('finish', () => console.log('Upload complete 📤'));

// Download a file
bucket.openDownloadStreamByName('photo.jpg')
  .pipe(fs.createWriteStream('./downloaded.jpg'));

Example

GridFS is commonly used for storing user-uploaded images, videos, or large binary blobs.

16. Error Handling ⚠️

Robust error handling distinguishes between driver-level errors, network errors, and validation errors.

error-handling.js

const { MongoServerError } = require('mongodb');

try {
  await usersCollection.insertOne({ _id: 1, name: 'Alice' });
  await usersCollection.insertOne({ _id: 1, name: 'Duplicate' });
} catch (err) {
  if (err instanceof MongoServerError && err.code === 11000) {
    console.error('Duplicate key error 🚫:', err.message);
  } else {
    console.error('Unexpected error:', err);
  }
}

Warning

Always wrap database operations in try/catch blocks, especially around network-sensitive calls like connect().

17. Connection Pooling 🏊

The driver maintains a pool of reusable connections per MongoClient instance rather than opening a new socket for every query.

pooling.js

const client = new MongoClient(uri, {
  maxPoolSize: 20,   // maximum simultaneous connections
  minPoolSize: 5,    // connections kept alive even when idle
  maxIdleTimeMS: 30000,
});

Option	Purpose
maxPoolSize	Caps concurrent connections per client
minPoolSize	Keeps a baseline of warm connections
maxIdleTimeMS	Closes connections idle beyond this duration

Best Practice

Reuse a single MongoClient instance across your entire application instead of creating one per request.

18. Environment Variables 🔐

Sensitive configuration — like connection URIs and credentials — should live in environment variables, never in source code.

my-app

.env

.gitignore

package.json

src

db.js

index.js

.env

MONGO_URI=mongodb+srv://user:pass@cluster0.mongodb.net/shopDB
NODE_ENV=production

db.js

require('dotenv').config();
const { MongoClient } = require('mongodb');

const client = new MongoClient(process.env.MONGO_URI);

Danger

Always add .env to .gitignore to prevent committing secrets to version control.

19. Async/Await ⏳

Nearly every driver method returns a Promise, making async/await the cleanest way to write sequential, readable database code.

async-await.js

async function getActiveUsers() {
  try {
    const users = await usersCollection
      .find({ status: 'active' })
      .toArray();
    return users;
  } catch (err) {
    console.error('Query failed:', err);
    throw err;
  }
}

Tip

Use Promise.all() to run independent queries concurrently instead of awaiting them one by one.

parallel-queries.js

const [users, orders] = await Promise.all([
  usersCollection.find({}).toArray(),
  ordersCollection.find({}).toArray(),
]);

20. Performance Optimization 🚀

Indexing

indexing.js

// Single field index
await usersCollection.createIndex({ email: 1 }, { unique: true });

// Compound index
await usersCollection.createIndex({ age: 1, name: -1 });

Query Profiling

explain.js

const explanation = await usersCollection
  .find({ age: { $gt: 25 } })
  .explain('executionStats');

console.log(explanation.executionStats.totalDocsExamined);

Use .explain() to detect full collection scans.
Limit fields returned using projections.
Avoid unbounded $regex queries without anchors.
Batch writes using bulkWrite() (see Section 13).

21. Security Best Practices 🛡️

Enable authentication and use RBAC with least-privilege roles.
Always connect via TLS/SSL in production.
Restrict network access with IP allow-lists or VPC peering.
Store credentials in environment variables or a secrets manager, never in code.
Sanitize user input to prevent NoSQLi attacks (e.g., avoid passing raw objects from request bodies directly into queries).

sanitize-example.js

// ❌ Dangerous: raw user input passed directly
const user = await usersCollection.findOne(req.body);

// ✅ Safer: explicitly whitelist expected fields
const user = await usersCollection.findOne({
  email: String(req.body.email),
});

Danger

Never trust client-supplied query objects directly — a malicious payload like { $gt: '' } can bypass intended logic.

22. Best Practices ✅

Reuse a single MongoClient instance app-wide.
Always close connections gracefully on process shutdown.
Use schema validation at the collection level even in a schema-less database.
Prefer async/await over callback-based code.
Log slow queries and monitor with tools like MongoDB Atlas Performance Advisor.

graceful-shutdown.js

process.on('SIGINT', async () => {
  await client.close();
  console.log('MongoDB connection closed 👋');
  process.exit(0);
});

23. Common Mistakes 🚫

Mistake	Why It's a Problem
Creating a new MongoClient per request	Exhausts connections and degrades performance
Not awaiting connect()	Leads to race conditions and intermittent failures
Ignoring indexes	Causes slow, full collection scans
Passing raw request bodies into queries	Opens the door to NoSQL injection
Not handling ObjectId casting	Causes silent query mismatches

Caution

Remember: an _id stored as an ObjectId will not match a plain string in a query unless explicitly cast with new ObjectId(str).

24. Frequently Asked Questions ❓

Question

Do I need Mongoose, or is the native driver enough?

Answer

It depends on your needs — the native driver is sufficient for most apps and offers more control, while Mongoose is helpful if you want schema enforcement and built-in validation out of the box.

Question

Can I use transactions on a standalone MongoDB instance?

Answer

No. Transactions require a replica set or sharded cluster deployment.

Question

How do I generate a new ObjectId?

Answer

Use new ObjectId() from the mongodb package.

25. Summary 📝

Summary

You've learned how to connect Node.js to MongoDB using the native driver, perform full CRUD operations, build aggregation pipelines, manage transactions and sessions, optimize performance with indexes, and apply essential security practices for production environments.

🔌

Connect via MongoClient and connection strings.

🛠️

Perform CRUD operations on collections.

📊

Leverage aggregation for analytics.

🔒

Ensure atomicity with transactions and sessions.

🚀

Optimize and secure your application for production.

>>The database is not just a place to store data — it's a tool for expressing the shape of your application's truth.

Official Docs: MongoDB Node.js Driver Documentation
Free Learning: MongoDB University

1. Introduction 🌱

ℹ️Information

Why MongoDB with Node.js? 🤔

2. MongoDB Node.js Driver 🚗

terminal

terminal

💡Tip

3. Connecting to MongoDB 🔌

connect.js

4. Connection Strings 🔗

.env

⚠️Warning

Common URI Options ⚙️

5. MongoClient 🧭

client.js

❗Important

6. Database Instances 🗄️

db-instance.js

7. Collection Instances 📁

collection-instance.js

📝Note

8. CRUD Operations 🛠️

Create ➕

create.js

Read 👀

read.js

Update ✏️

update.js

Delete 🗑️

delete.js

9. Querying Documents 🔍

Comparison Operators

query-comparison.js

Logical Operators

query-logical.js

Projection, Sorting & Pagination

query-advanced.js

⭐Best Practice

10. Aggregation 📊

aggregation.js

11. Transactions 🔒

transactions.js

🟡Caution

12. Sessions 🎫

sessions.js

🔗Reference

13. Bulk Operations 📦

bulk-operations.js

💡Tip

14. Change Streams 📡

change-streams.js

ℹ️Information

15. GridFS 🖼️

gridfs.js

📖Example

16. Error Handling ⚠️

error-handling.js

⚠️Warning

17. Connection Pooling 🏊

pooling.js

⭐Best Practice

18. Environment Variables 🔐

.env

db.js

🚫Danger

19. Async/Await ⏳

async-await.js

💡Tip

parallel-queries.js

20. Performance Optimization 🚀

Indexing

indexing.js

Query Profiling

explain.js

21. Security Best Practices 🛡️

sanitize-example.js

🚫Danger

22. Best Practices ✅

graceful-shutdown.js

23. Common Mistakes 🚫

Information

Tip

Warning

Important

Note

Best Practice

Caution

Reference

Tip

Information

Example

Warning

Best Practice

Danger

Tip

Danger

Caution

Question

Answer

Question

Answer

Question

Answer

Summary