Mongoose tutorial: a MongoDB & NoSQL guide for developers

Introduction

By Day 39 of building with MongoDB, you've seen the flexibility of NoSQL—but you've also felt the pain of unstructured data. Mongoose tutorial: a MongoDB & NoSQL guide for developers shows you how to reclaim that structure without sacrificing the agility that attracted you to MongoDB in the first place. In this guide, we'll walk through defining schemas, running optimized queries, hooking into lifecycle events, and indexing strategically—the patterns our teams rely on daily in production.

Define a Schema: Types, Validation, and Defaults

A Mongoose schema is where discipline meets flexibility. Unlike raw MongoDB, which lets you insert anything, a schema enforces a contract: every document in a collection must conform to the shape you define. This catches bugs early and makes your codebase far more maintainable as teams scale.

Start with the basics. Here's a real product schema we use in an e-commerce platform:

const mongoose = require('mongoose');
const { Schema, model } = mongoose;

const productSchema = new Schema(
  {
    name: {
      type: String,
      required: true,
      trim: true,
      minlength: 3,
      maxlength: 200
    },
    price: {
      type: Number,
      min: 0,
      required: true
    },
    description: String,
    tags: [String],
    inventory: {
      stock: {
        type: Number,
        default: 0,
        min: 0
      },
      lastUpdated: Date
    },
    active: {
      type: Boolean,
      default: true
    }
  },
  { timestamps: true }
);

const Product = model('Product', productSchema);

module.exports = Product;

Notice the structure here. The name field is a String with required: true—Mongoose won't save the document if name is missing. We also set minlength and maxlength to validate the string length at the database layer, not just in your API.

The price field uses a min validator to prevent negative values. This catches logic errors before they corrupt your database. The tags array accepts an array of strings. The nested inventory object shows how to structure related fields together.

The timestamps: true option adds createdAt and updatedAt fields automatically. This eliminates boilerplate and keeps your audit trail clean. Lean on defaults and built-in validators wherever you can; they're faster than application-level checks and guaranteed to run on every save.

Custom validation is equally important. Here's how we validate an email in a user schema:

const userSchema = new Schema({
  email: {
    type: String,
    required: true,
    lowercase: true,
    match: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
  },
  role: {
    type: String,
    enum: ['admin', 'user', 'guest'],
    default: 'user'
  }
});

The match validator rejects invalid emails at save time. The enum constraint restricts role to a fixed set of values. These constraints prevent bad data from ever reaching your database.

Queries: Lean Reads and Efficient Retrieval

Mongoose makes querying intuitive, but the default behavior includes hydration—converting raw MongoDB documents into Mongoose Document objects. This adds overhead. For read-heavy operations, especially in high-throughput systems, use .lean() to bypass hydration and get plain JavaScript objects.

Consider a product listing endpoint that needs to fetch hundreds of products. Here's the overhead-aware approach:

// Slow: returns Mongoose documents with all methods
app.get('/products', async (req, res) => {
  const products = await Product.find({ active: true });
  res.json(products);
});

// Fast: returns plain objects, ideal for JSON responses
app.get('/products', async (req, res) => {
  const products = await Product
    .find({ active: true })
    .lean()
    .limit(50)
    .sort({ createdAt: -1 });
  res.json(products);
});

The second approach is measurably faster. We're not converting to Mongoose Documents, not loading virtual fields, not attaching methods. We get raw data in microseconds.

For operations where you need to call .save() or other Mongoose methods, don't use .lean(). But for APIs, caching, and background workers that only read data, always reach for lean reads.

Chaining other query methods works seamlessly. .select() picks specific fields, reducing payload size:

const products = await Product
  .find({ active: true })
  .select('name price tags')
  .lean()
  .limit(20);

This returns only the fields you need. It's a small optimization that compounds across thousands of requests.

Middleware: Pre and Post Hooks for Save and Delete

Mongoose middleware, also called hooks, runs at key lifecycle points: before or after save, update, delete, and query execution. This is where you enforce business logic, audit changes, or clean up related data.

We use pre hooks to hash passwords before save, normalize data, or validate related entities:

const bcrypt = require('bcrypt');

userSchema.pre('save', async function (next) {
  // Only hash if password has changed
  if (!this.isModified('password')) {
    return next();
  }

  try {
    const salt = await bcrypt.genSalt(10);
    this.password = await bcrypt.hash(this.password, salt);
    next();
  } catch (error) {
    next(error);
  }
});

// Prevent password from being returned in queries
userSchema.post('save', function (doc) {
  doc.password = undefined;
});

The pre('save') hook runs before the document is written to the database. We hash the password if it's new or modified. The next() call signals Mongoose to continue. If we pass an error to next(error), the save fails and the error bubbles up.

Post hooks are useful for side effects. After saving a user, we might emit an event to a message queue or log an audit entry:

userSchema.post('save', async function (doc) {
  // Emit event for downstream services
  await eventBus.publish('user.created', {
    userId: doc._id,
    email: doc.email,
    timestamp: new Date()
  });
});

For delete operations, pre hooks are critical. When deleting a user, cascade delete their related documents:

userSchema.pre('deleteOne', { document: true }, async function (next) {
  const userId = this._id;
  // Delete user's orders, comments, settings, etc.
  await Order.deleteMany({ userId });
  await Comment.deleteMany({ userId });
  next();
});

Without this hook, you'd leave orphaned data. With it, your database stays consistent.

A final pattern: cache invalidation. When a product price changes, invalidate the product cache so downstream systems see fresh data:

productSchema.pre('save', async function (next) {
  if (this.isModified('price')) {
    await cache.del(`product:${this._id}`);
  }
  next();
});

Indexes: Declare Indexes on the Schema

MongoDB queries are fast until they're not. Without indexes, every query scans the entire collection. At scale, this turns into multi-second latencies or timeouts. Declare indexes on your schema to guarantee query performance.

Single-field indexes are the foundation. If you query by email frequently, index it:

userSchema.index({ email: 1 });

// Or make it unique
userSchema.index({ email: 1 }, { unique: true });

The 1 means ascending order; -1 means descending. A unique index prevents duplicates—Mongoose will reject a save if an email already exists.

Compound indexes optimize queries filtering on multiple fields:

// Query: find orders by user and status
orderSchema.index({ userId: 1, status: 1 });

// This query will be fast
const orders = await Order
  .find({ userId: user._id, status: 'pending' })
  .lean();

Order matters in compound indexes. Put fields that filter most rows first, then fields with lower selectivity.

For time-series data, TTL indexes auto-delete old documents:

// Auto-delete sessions after 24 hours
sessionSchema.index({ createdAt: 1 }, { expireAfterSeconds: 86400 });

Text indexes enable full-text search:

productSchema.index({ name: 'text', description: 'text' });

// Query
const results = await Product.find({ $text: { $search: 'wireless headphones' } });

Always measure. In development, query performance feels fine. In production, with millions of documents, unindexed queries become production incidents. Use MongoDB's explain plan to verify indexes are being used:

const explanation = await Product
  .find({ active: true, price: { $gt: 100 } })
  .explain('executionStats');

console.log(explanation.executionStats.executionStages.stage);
// If it says "COLLSCAN", you're scanning every document. Add an index.

Common Mistakes

• Forgetting to call next() in middleware. Your middleware will hang silently. Always call next() or next(error) at the end of every hook.
• Using .lean() for data you need to modify. Lean objects don't have save methods. If you're updating the document, keep it as a Mongoose Document.
• Not indexing query fields in production. Test with millions of rows. Indexes that seem unnecessary in development become critical at scale.
• Over-validating on the schema. Some validation belongs in your application logic or a dedicated validator library. Schema validation is for constraints, not business rules.
• Creating indexes after data exists. On large collections, index creation can lock writes. Create indexes during maintenance windows or use background index builds.

Key Takeaways

• Schemas enforce data shape and catch bugs early. Use required, min, max, enum, and custom validators to prevent invalid data from reaching your database.
• Lean reads with .lean() are essential for high-throughput read paths. They bypass Mongoose hydration and return plain objects, cutting latency by 30-50% in typical workloads.
• Pre and post hooks centralize business logic—hashing passwords, cascading deletes, emitting events. Keep them side-effect-free and always handle errors gracefully.
• Indexes are non-negotiable at production scale. Single-field indexes on frequently queried columns, compound indexes for multi-field filters, and explain plans to verify they're being used.
• Mongoose is a bridge between the structure of SQL and the flexibility of NoSQL. Use it to enforce contracts without sacrificing MongoDB's schema-less power.