MongoDB Modeling with Mongoose: Schemas, Query Operators, Middleware Hooks, Methods and Virtuals

By 0xmote · Aug 21, 2026 · 34 min read · Updated Sep 27, 2026 Intermediate tutorial

Key takeaways

Mongoose is a MongoDB object modeling tool for Node.js. It provides schema-based validation, middleware, queries, and a elegant API for working with MongoDB.

Introduction

Mongoose is an Object Data Modeling (ODM) library for MongoDB and Node.js. It provides a schema-based solution to model your data with built-in validation, queries, and business logic.

Why Mongoose?

Native MongoDB driver:

const db = client.db('myapp');
const users = db.collection('users');

// No schema, no validation
await users.insertOne({ name: 'Alice', age: 'invalid' }); // Inserts anything!

With Mongoose:

const userSchema = new mongoose.Schema({
  name: { type: String, required: true },
  age: { type: Number, min: 0 },
});

const User = mongoose.model('User', userSchema);

await User.create({ name: 'Alice', age: 'invalid' }); // Validation error!

The difference between these two snippets is the entire reason Mongoose exists. MongoDB itself is schemaless — the server will happily accept a document where age is a string, a document with an extra typo’d field, or a document missing a field entirely. That flexibility is a feature when you are prototyping or storing genuinely heterogeneous data, but in most application code it just relocates every validation concern into your request handlers, where it gets duplicated, forgotten, or implemented inconsistently across a team. Mongoose moves that contract to a single place — the schema — and enforces it before a document ever reaches the wire.

That said, the abstraction is not free. Every save() or create() call runs the full validation pipeline (including any custom validators and hooks you register), which adds CPU overhead compared to calling the native driver directly. Mongoose also builds a full document wrapper — complete with change tracking, virtuals, and getters/setters — around every object it returns from a query, which costs more memory and time to construct than a plain JSON object from the native driver. For a handful of requests per second this overhead is irrelevant; for a hot path processing tens of thousands of documents per second (bulk ETL jobs, analytics ingestion, log pipelines), it can become the bottleneck. That’s exactly the scenario where .lean() (covered later) or the native driver itself becomes the better choice. A practical rule of thumb: use Mongoose for anything that looks like your application’s core domain model (users, orders, posts), and drop to the native driver or .lean() for high-throughput, write-once/read-rarely data.

Installation

npm install mongoose

Connection

const mongoose = require('mongoose');

// Connect to MongoDB
await mongoose.connect('mongodb://localhost:27017/myapp');

// Or with options
await mongoose.connect(process.env.MONGODB_URI, {
  useNewUrlParser: true,
  useUnifiedTopology: true,
});

// Handle connection events
mongoose.connection.on('connected', () => {
  console.log('MongoDB connected');
});

mongoose.connection.on('error', (err) => {
  console.error('MongoDB error:', err);
});

mongoose.connection.on('disconnected', () => {
  console.log('MongoDB disconnected');
});

mongoose.connect() does not open a single socket — it opens a connection pool (10 sockets by default, configurable via maxPoolSize), and every query you run borrows a socket from that pool for the duration of the request. This is why calling mongoose.connect() more than once per process is a real production bug, not just an inefficiency: each call spins up a brand-new pool, and if you do it inside a request handler (rather than once at startup) you can exhaust MongoDB’s maxConns limit under load, causing connection errors that only show up in production traffic, not in local testing.

This bites people hardest in serverless environments (AWS Lambda, Cloudflare Workers, Vercel Functions), where the natural instinct is to connect inside the handler because there’s no explicit “server startup” phase. The fix is to cache the connection promise outside the handler function so a warm invocation reuses the existing pool instead of opening a new one:

// db.js — connection caching for serverless environments
let conn = null;

async function connectToDatabase() {
  if (conn && mongoose.connection.readyState === 1) {
    return conn; // Reuse existing connection on warm start
  }
  conn = await mongoose.connect(process.env.MONGODB_URI, {
    maxPoolSize: 5, // Keep this low — each concurrent function instance opens its own pool
    serverSelectionTimeoutMS: 5000,
  });
  return conn;
}

module.exports = connectToDatabase;

A related gotcha: by default Mongoose buffers commands issued before the connection finishes (bufferCommands: true), silently queueing your queries until connect() resolves. This is convenient for simple scripts but can mask a genuinely broken connection string — your app will hang instead of failing fast. In production, it’s usually worth setting bufferCommands: false and explicitly awaiting the connection before starting your HTTP server, so a misconfigured MONGODB_URI fails loudly at boot instead of causing mysteriously “stuck” requests later.

Schema Definition

const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({
  // String
  name: {
    type: String,
    required: [true, 'Name is required'],
    trim: true,
    minlength: 2,
    maxlength: 50,
  },
  
  // Email with validation
  email: {
    type: String,
    required: true,
    unique: true,
    lowercase: true,
    match: [/^\S+@\S+\.\S+$/, 'Invalid email format'],
  },
  
  // Number
  age: {
    type: Number,
    min: [0, 'Age must be positive'],
    max: 120,
  },
  
  // Enum
  role: {
    type: String,
    enum: ['user', 'admin', 'moderator'],
    default: 'user',
  },
  
  // Boolean
  isActive: {
    type: Boolean,
    default: true,
  },
  
  // Date
  createdAt: {
    type: Date,
    default: Date.now,
  },
  
  // Array
  tags: [String],
  
  // Nested object
  address: {
    street: String,
    city: String,
    zipCode: String,
  },
  
  // Reference to another model
  posts: [{
    type: mongoose.Schema.Types.ObjectId,
    ref: 'Post',
  }],
});

const User = mongoose.model('User', userSchema);

Notice that the schema mixes two different kinds of constraints: structural ones (type: String) and business-rule ones (required, min, max, match, enum). It’s tempting to push every rule your application needs into the schema, but that trades short-term convenience for long-term rigidity. A unique: true index, for example, is enforced at the database level and requires an index rebuild to change — fine for something like email, painful if you add it speculatively to a field whose uniqueness requirements later turn out to be conditional (e.g., “unique per tenant” instead of globally unique). A good default is: put constraints that are true regardless of business context (a price can’t be negative, an email must look like an email) in the schema, and push constraints that depend on application state or vary by feature flag into your service layer instead.

The nested address object above is also worth pausing on. Mongoose treats it as a subdocument by default (single embedded object, no separate collection), which is the right call when the data is always read and written together with the parent and never queried independently — an address genuinely only makes sense in the context of its user. Contrast that with posts: [{ type: ObjectId, ref: 'Post' }], which is a reference to documents that live in their own collection because posts are independently queried, updated, and paginated all the time. Getting this choice backwards is one of the most common MongoDB schema-design mistakes: embedding data that grows unbounded (e.g., embedding every comment inside a blog post document) eventually hits MongoDB’s 16MB document size limit, while referencing data that’s always accessed together with its parent (e.g., a profile object) forces an extra query for no benefit.

CRUD Operations

Create

// Method 1: create()
const user = await User.create({
  name: 'Alice',
  email: '[email protected]',
  age: 30,
});

// Method 2: new + save()
const user = new User({
  name: 'Bob',
  email: '[email protected]',
});
await user.save();

// Create multiple
await User.insertMany([
  { name: 'Charlie', email: '[email protected]' },
  { name: 'David', email: '[email protected]' },
]);

Read

// Find all
const users = await User.find();

// Find with filter
const activeUsers = await User.find({ isActive: true });

// Find one
const user = await User.findOne({ email: '[email protected]' });

// Find by ID
const user = await User.findById('507f1f77bcf86cd799439011');

// With projection (select fields)
const users = await User.find().select('name email');

// With sorting
const users = await User.find().sort({ createdAt: -1 });

// With limit and skip (pagination)
const users = await User.find()
  .limit(10)
  .skip(20)
  .sort({ createdAt: -1 });

// Count
const count = await User.countDocuments({ isActive: true });

Update

// Update one
await User.updateOne(
  { email: '[email protected]' },
  { $set: { age: 31 } }
);

// Update many
await User.updateMany(
  { isActive: false },
  { $set: { isActive: true } }
);

// Find and update (returns updated document)
const user = await User.findOneAndUpdate(
  { email: '[email protected]' },
  { $set: { age: 31 } },
  { new: true } // Return updated document
);

// Update by ID
const user = await User.findByIdAndUpdate(
  '507f1f77bcf86cd799439011',
  { $set: { age: 31 } },
  { new: true }
);

Delete

// Delete one
await User.deleteOne({ email: '[email protected]' });

// Delete many
await User.deleteMany({ isActive: false });

// Find and delete (returns deleted document)
const user = await User.findOneAndDelete({ email: '[email protected]' });

// Delete by ID
await User.findByIdAndDelete('507f1f77bcf86cd799439011');

A subtlety that trips up a lot of newcomers: create() and new User() + save() both trigger full schema validation and any pre('save') hooks you’ve registered, while updateOne(), updateMany(), findOneAndUpdate(), and similar bulk-style operations do not run validation or save middleware by default. If your password-hashing logic lives in a pre('save') hook (as it does in the Middleware section below), calling User.updateOne({ _id }, { password: 'plaintext' }) will silently write an unhashed password to the database — no error, no hook fired. To force validation on an update you need { runValidators: true }, and hooks that specifically target save still won’t run; you’d need a pre('updateOne') hook (or a pre(/^find/) catch-all) if you want update-path logic to fire consistently. This single gap between the “document” API (save()) and the “query” API (updateOne()) is one of the most common sources of “why didn’t my validation/hashing run?” bugs in real Mongoose codebases.

insertMany() deserves its own callout too: it is far faster than looping over create() because it batches everything into a single round trip to MongoDB instead of one round trip per document, but by default a single failing document aborts the whole batch and previously-inserted documents in that batch are not rolled back (MongoDB does not do multi-document transactions unless you explicitly start a session). If you need all-or-nothing semantics across multiple documents, wrap the operation in a session-based transaction; if you just want inserts to continue past a bad document, pass { ordered: false } so MongoDB attempts every document and reports failures at the end.

Query Operators

// Comparison
User.find({ age: { $gt: 18 } });           // Greater than
User.find({ age: { $gte: 18 } });          // Greater than or equal
User.find({ age: { $lt: 65 } });           // Less than
User.find({ age: { $lte: 65 } });          // Less than or equal
User.find({ age: { $ne: 30 } });           // Not equal

// Logical
User.find({
  $and: [
    { age: { $gte: 18 } },
    { age: { $lte: 65 } }
  ]
});

User.find({
  $or: [
    { role: 'admin' },
    { role: 'moderator' }
  ]
});

// In/Not in
User.find({ role: { $in: ['admin', 'moderator'] } });
User.find({ role: { $nin: ['banned', 'suspended'] } });

// Exists
User.find({ email: { $exists: true } });

// Regex
User.find({ name: { $regex: /^A/i } }); // Names starting with A

Middleware (Hooks)

const bcrypt = require('bcrypt');

const userSchema = new mongoose.Schema({
  email: String,
  password: String,
});

// Pre-save hook
userSchema.pre('save', async function(next) {
  // Only hash if password is modified
  if (!this.isModified('password')) return next();
  
  // Hash password
  this.password = await bcrypt.hash(this.password, 10);
  next();
});

// Post-save hook
userSchema.post('save', function(doc) {
  console.log('User saved:', doc._id);
});

// Pre-remove hook
userSchema.pre('remove', async function(next) {
  // Delete user's posts
  await Post.deleteMany({ author: this._id });
  next();
});

const User = mongoose.model('User', userSchema);

// Usage
const user = new User({ email: '[email protected]', password: 'password123' });
await user.save(); // Password automatically hashed

Three practical gotchas with hooks come up constantly in production code:

Arrow functions break this binding. Mongoose hooks rely on this referring to the document being saved, which only works with a regular function expression. Writing userSchema.pre('save', async () => { ... }) compiles fine and fails silently at runtime — this inside an arrow function is lexically scoped to whatever enclosed it (often undefined or the module scope), not the document, so this.isModified(...) and this.password won’t do what you expect.
Hook order matters and is easy to get backwards. Multiple pre('save') hooks on the same schema run in registration order, and if one hook depends on a field another hook computes (e.g., a slug-generation hook that needs a title already trimmed by an earlier hook), swapping the registration order silently changes behavior. Keep related hooks near each other in the file and comment on cross-hook dependencies.
remove is deprecated in favor of deleteOne/deleteMany document middleware, and the two are not interchangeable — the cascading delete pattern shown above (pre('remove') deleting a user’s posts) will not fire if your code calls Model.deleteOne() or Model.findByIdAndDelete() instead of document.remove(), since those are query-level operations that bypass document middleware entirely. If cascading deletes matter for your data model, either register pre('deleteOne', { document: true, query: false }, ...) explicitly, or move the cascade logic out of Mongoose hooks and into an explicit service-layer function that callers use consistently — hooks that only fire for one of several equivalent deletion paths are a common source of orphaned records.

Instance Methods

const userSchema = new mongoose.Schema({
  email: String,
  password: String,
});

// Add instance method
userSchema.methods.verifyPassword = async function(password) {
  return await bcrypt.compare(password, this.password);
};

userSchema.methods.toPublicJSON = function() {
  return {
    id: this._id,
    email: this.email,
    // Don't include password
  };
};

const User = mongoose.model('User', userSchema);

// Usage
const user = await User.findOne({ email: '[email protected]' });
const isValid = await user.verifyPassword('password123');
const publicData = user.toPublicJSON();

Static Methods

// Add static method
userSchema.statics.findByEmail = function(email) {
  return this.findOne({ email: email.toLowerCase() });
};

userSchema.statics.findActiveUsers = function() {
  return this.find({ isActive: true });
};

const User = mongoose.model('User', userSchema);

// Usage
const user = await User.findByEmail('[email protected]');
const activeUsers = await User.findActiveUsers();

Virtual Fields

const userSchema = new mongoose.Schema({
  firstName: String,
  lastName: String,
});

// Virtual property (not stored in DB)
userSchema.virtual('fullName')
  .get(function() {
    return `${this.firstName} ${this.lastName}`;
  })
  .set(function(name) {
    const parts = name.split(' ');
    this.firstName = parts[0];
    this.lastName = parts[1];
  });

// Enable virtuals in JSON
userSchema.set('toJSON', { virtuals: true });

const User = mongoose.model('User', userSchema);

// Usage
const user = new User({ firstName: 'Alice', lastName: 'Smith' });
console.log(user.fullName); // "Alice Smith"

user.fullName = 'Bob Johnson';
console.log(user.firstName); // "Bob"
console.log(user.lastName); // "Johnson"

Population (Relations)

const postSchema = new mongoose.Schema({
  title: String,
  content: String,
  author: {
    type: mongoose.Schema.Types.ObjectId,
    ref: 'User',
  },
});

const Post = mongoose.model('Post', postSchema);

// Create post
const post = await Post.create({
  title: 'My First Post',
  content: 'Hello world',
  author: user._id, // User's ObjectId
});

// Populate author
const postWithAuthor = await Post.findById(post._id).populate('author');
console.log(postWithAuthor.author.name); // "Alice"

// Populate specific fields
const post = await Post.findById(postId)
  .populate('author', 'name email');

// Nested populate
const post = await Post.findById(postId)
  .populate({
    path: 'author',
    populate: { path: 'company' }
  });

populate() is convenient, but it’s important to understand what it actually does under the hood: it is not a MongoDB join. Mongoose runs your original query, collects the referenced ObjectIds from the results, then issues one or more additional queries to fetch the referenced documents and stitches them back onto the results in application code. For a single findById().populate('author') this is one extra query and completely fine. The trouble starts when populate is called inside a loop, or on a large result set with a ref field — Post.find().populate('author') on 500 posts still only issues two queries total (one for posts, one $in query for all distinct authors), which is reasonable, but nested populate chains (populate({ path: 'author', populate: { path: 'company' } })) multiply this out and can turn what looks like one line of code into several sequential round trips to the database, each one blocking on the last.

For anything beyond one or two levels of relationship, or for reporting/dashboard-style queries where you’re already reaching for aggregation, $lookup in an aggregation pipeline resolves the same relational data in a single query executed entirely on the database server:

// Equivalent to .populate('author'), but resolved server-side in one query
const posts = await Post.aggregate([
  { $match: { published: true } },
  {
    $lookup: {
      from: 'users',        // The actual MongoDB collection name
      localField: 'author',
      foreignField: '_id',
      as: 'author',
    },
  },
  { $unwind: '$author' },   // populate() returns a single object, not an array
]);

The trade-off is that aggregation pipelines lose Mongoose’s document features (no .save(), no virtuals, no hooks on the results — you get plain objects), so reach for populate() for normal CRUD-style reads and switch to $lookup when you’re already doing aggregation or profiling shows populate-heavy endpoints as a bottleneck. Either way, always index the field you’re joining on (author in this example already gets one implicitly via ref, but double-check with .explain() on any query you suspect is slow) — a $lookup or populate() against an unindexed foreign key degrades to a full collection scan per lookup.

Validation

const productSchema = new mongoose.Schema({
  name: {
    type: String,
    required: [true, 'Product name is required'],
    minlength: [3, 'Name must be at least 3 characters'],
  },
  price: {
    type: Number,
    required: true,
    min: [0, 'Price must be positive'],
    validate: {
      validator: function(v) {
        return v > 0;
      },
      message: 'Price must be greater than 0',
    },
  },
  category: {
    type: String,
    enum: {
      values: ['electronics', 'clothing', 'food'],
      message: '{VALUE} is not a valid category',
    },
  },
  email: {
    type: String,
    validate: {
      validator: function(v) {
        return /^\S+@\S+\.\S+$/.test(v);
      },
      message: props => `${props.value} is not a valid email`,
    },
  },
});

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

// Validation happens on save
try {
  await Product.create({ name: 'AB', price: -10 });
} catch (error) {
  console.error(error.errors);
  // ValidationError: name: Name must be at least 3 characters
  // ValidationError: price: Price must be positive
}

TypeScript Integration

import mongoose, { Document, Schema } from 'mongoose';

interface IUser extends Document {
  name: string;
  email: string;
  age: number;
  createdAt: Date;
  verifyPassword(password: string): Promise<boolean>;
}

const userSchema = new Schema<IUser>({
  name: { type: String, required: true },
  email: { type: String, required: true, unique: true },
  age: { type: Number, min: 0 },
  createdAt: { type: Date, default: Date.now },
});

userSchema.methods.verifyPassword = async function(password: string) {
  return await bcrypt.compare(password, this.password);
};

const User = mongoose.model<IUser>('User', userSchema);

// Usage with full type safety
const user: IUser = await User.create({
  name: 'Alice',
  email: '[email protected]',
  age: 30,
});

console.log(user.name); // TypeScript knows it's a string
const isValid = await user.verifyPassword('password123'); // TypeScript knows the method

Real-World Example: Blog API

const mongoose = require('mongoose');

// User schema
const userSchema = new mongoose.Schema({
  username: { type: String, required: true, unique: true },
  email: { type: String, required: true, unique: true },
  password: { type: String, required: true },
  role: { type: String, enum: ['user', 'admin'], default: 'user' },
  createdAt: { type: Date, default: Date.now },
});

userSchema.methods.verifyPassword = async function(password) {
  return await bcrypt.compare(password, this.password);
};

const User = mongoose.model('User', userSchema);

// Post schema
const postSchema = new mongoose.Schema({
  title: { type: String, required: true },
  slug: { type: String, required: true, unique: true },
  content: { type: String, required: true },
  excerpt: { type: String, maxlength: 300 },
  author: { type: mongoose.Schema.Types.ObjectId, ref: 'User', required: true },
  tags: [String],
  published: { type: Boolean, default: false },
  views: { type: Number, default: 0 },
  createdAt: { type: Date, default: Date.now },
  updatedAt: { type: Date, default: Date.now },
});

// Auto-update updatedAt
postSchema.pre('save', function(next) {
  this.updatedAt = Date.now();
  next();
});

// Generate slug from title
postSchema.pre('save', function(next) {
  if (this.isModified('title')) {
    this.slug = this.title.toLowerCase().replace(/\s+/g, '-');
  }
  next();
});

const Post = mongoose.model('Post', postSchema);

// Comment schema
const commentSchema = new mongoose.Schema({
  post: { type: mongoose.Schema.Types.ObjectId, ref: 'Post', required: true },
  author: { type: mongoose.Schema.Types.ObjectId, ref: 'User', required: true },
  content: { type: String, required: true, maxlength: 1000 },
  createdAt: { type: Date, default: Date.now },
});

const Comment = mongoose.model('Comment', commentSchema);

Express API with Mongoose

const express = require('express');
const mongoose = require('mongoose');

const app = express();
app.use(express.json());

// Connect to MongoDB
await mongoose.connect(process.env.MONGODB_URI);

// Get all posts
app.get('/api/posts', async (req, res) => {
  try {
    const { page = 1, limit = 10 } = req.query;
    
    const posts = await Post.find({ published: true })
      .populate('author', 'username')
      .sort({ createdAt: -1 })
      .limit(limit)
      .skip((page - 1) * limit);
    
    const total = await Post.countDocuments({ published: true });
    
    res.json({
      posts,
      page: parseInt(page),
      totalPages: Math.ceil(total / limit),
      total,
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Get single post
app.get('/api/posts/:slug', async (req, res) => {
  try {
    const post = await Post.findOne({ slug: req.params.slug })
      .populate('author', 'username email');
    
    if (!post) {
      return res.status(404).json({ error: 'Post not found' });
    }
    
    // Increment views
    post.views += 1;
    await post.save();
    
    res.json({ post });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Create post
app.post('/api/posts', authenticate, async (req, res) => {
  try {
    const post = await Post.create({
      ...req.body,
      author: req.user.id,
    });
    
    res.status(201).json({ post });
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

// Update post
app.put('/api/posts/:id', authenticate, async (req, res) => {
  try {
    const post = await Post.findById(req.params.id);
    
    if (!post) {
      return res.status(404).json({ error: 'Post not found' });
    }
    
    // Check ownership
    if (post.author.toString() !== req.user.id) {
      return res.status(403).json({ error: 'Unauthorized' });
    }
    
    Object.assign(post, req.body);
    await post.save();
    
    res.json({ post });
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

// Delete post
app.delete('/api/posts/:id', authenticate, async (req, res) => {
  try {
    const post = await Post.findById(req.params.id);
    
    if (!post) {
      return res.status(404).json({ error: 'Post not found' });
    }
    
    if (post.author.toString() !== req.user.id) {
      return res.status(403).json({ error: 'Unauthorized' });
    }
    
    await post.remove();
    
    res.json({ message: 'Post deleted' });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

Indexes

const userSchema = new mongoose.Schema({
  email: { type: String, required: true, unique: true },
  username: { type: String, required: true },
  createdAt: { type: Date, default: Date.now },
});

// Single field index
userSchema.index({ email: 1 });

// Compound index
userSchema.index({ username: 1, createdAt: -1 });

// Text index for search
postSchema.index({ title: 'text', content: 'text' });

// Usage
const posts = await Post.find({ $text: { $search: 'mongodb tutorial' } });

One timing detail that surprises a lot of teams the first time they hit it in production: calling schema.index(...) does not create the index immediately. Mongoose builds indexes asynchronously in the background the first time a model connects, and by default it does this automatically (autoIndex: true) — which is fine in development but risky in production, because an index build on a large existing collection can be a long-running, resource-intensive operation that you generally want to schedule and monitor deliberately rather than have kick off implicitly whenever your app happens to redeploy. The standard production pattern is to set autoIndex: false in your connection options and create/manage indexes explicitly through a migration script or mongosh, so index builds are a deliberate, observable operation rather than a side effect of an app restart.

Read-path settings that matter under load

Lean queries and what they skip

// Regular query (returns Mongoose document)
const user = await User.findById(id);
user.save(); // Has methods

// Lean query (returns plain JS object)
const user = await User.findById(id).lean();
// user.save() is undefined - no methods

.lean() skips hydrating each result into a Mongoose document, which saves memory and CPU on large result sets, but it also skips everything the document layer would have done. Virtuals are missing, getters do not run, and schema defaults are not applied to fields absent from the stored document, so a response that looked right with a hydrated query can suddenly lack fullName or a default role. _id also stays an ObjectId instance rather than a string. Use lean for read-only endpoints that serialize straight to JSON, and check the response shape when switching an existing query to it.

Pagination that stays fast on later pages

async function getUsers(page = 1, limit = 10) {
  const users = await User.find()
    .limit(limit)
    .skip((page - 1) * limit)
    .sort({ createdAt: -1 });
  
  const total = await User.countDocuments();
  
  return {
    users,
    page,
    totalPages: Math.ceil(total / limit),
  };
}

Offset pagination is simple, but skip(n) still makes the server walk past n index entries, so page 5,000 is much slower than page 1, and the extra countDocuments() runs on every request. For feeds and infinite scroll, range-based pagination scales better: sort by an indexed field and ask for the next page relative to the last item the client saw, for example User.find({ createdAt: { $lt: lastSeenCreatedAt } }).sort({ createdAt: -1 }).limit(limit). Add _id as a tie-breaker if several documents can share the same timestamp, otherwise items at a page boundary can be skipped or repeated.

A query timeout so one slow scan cannot drain the pool

// Without a timeout, a slow query (missing index, huge scan) can hang
// a request indefinitely and exhaust your connection pool.
const users = await User.find({ isActive: true }).maxTimeMS(5000);

A single unindexed query under real traffic doesn’t just make one request slow — it holds a connection from the pool for the duration of the scan, and if enough requests pile up waiting on the same slow query pattern, the entire pool can be exhausted, taking down unrelated endpoints that happen to share the same connection. maxTimeMS() (or a global socketTimeoutMS on the connection) turns a silent hang into a fast, loud failure you can alert on.

When Not to Reach for Mongoose

Mongoose is a strong default for typical CRUD-heavy Node.js applications, but it isn’t the right tool in every situation:

High-throughput data pipelines. If you’re ingesting millions of events per hour (analytics, IoT telemetry, log aggregation), the per-document overhead of schema validation, change tracking, and document hydration adds up. The native MongoDB driver (or .insertMany() with .lean() reads) avoids that overhead entirely.
Read-heavy analytical/reporting queries. Complex aggregation pipelines, multi-collection joins, and large $group operations are more naturally expressed and more performant against the native driver’s db.collection.aggregate(), since Mongoose adds no real value on top of a plain aggregation call.
Highly dynamic, truly schemaless data. If your documents genuinely have no consistent shape (user-defined form submissions with arbitrary fields, for example), forcing them through a rigid schema with Schema.Types.Mixed everywhere gives you the worst of both worlds — the validation overhead of Mongoose without the safety benefit, since Mixed fields skip type checking.
Multi-document ACID transactions across many collections. Mongoose supports sessions and transactions, but the API is a thinner wrapper than it looks, and teams that need transactions as a core part of their data model often find it clearer to reason about them directly against the native driver’s session API.

Troubleshooting Common Issues

“Cast to ObjectId failed” errors. This almost always means a string that isn’t a valid 24-character hex ObjectId was passed to a query expecting one (a common cause: forgetting to validate req.params.id before calling findById). Validate the ID format (or wrap the query in a try/catch and return a 400) before hitting the database, rather than letting Mongoose’s cast error surface as an unhandled 500.

MongooseServerSelectionError on connect. This is a network/configuration problem, not a code bug: check that your IP is allow-listed (MongoDB Atlas blocks unknown IPs by default), that the connection string’s credentials are correct, and that serverSelectionTimeoutMS is set to something reasonable (the default of 30 seconds means a genuinely broken connection string can make your app appear to hang for half a minute before failing).

Documents saved but reads don’t reflect the change immediately. Mongoose’s default read preference is primary, so this is rarely a Mongoose issue — it’s usually application code re-reading a cached copy of the document, or an eventual-consistency assumption leaking in from a replica read preference (secondaryPreferred) configured elsewhere in the connection string.

Schema changes not taking effect. Mongoose compiles a model from its schema exactly once, the first time mongoose.model('Name', schema) runs for that name in the process. If you edit a schema file but a stale model is still cached (common with hot-reloading dev servers or when a model is accidentally required twice with two different schemas), you’ll see validation behavior that doesn’t match the schema on disk. Restarting the process — not just saving the file — is sometimes the actual fix.

Frequently Asked Questions (FAQ)

Q. When should I actually reach for Mongoose instead of the native driver?

A. Use Mongoose when your application has a core domain model that benefits from consistent validation, reusable query logic (statics/instance methods), and lifecycle hooks — typical CRUD backends, admin panels, and REST/GraphQL APIs. Reach for the native driver instead when you’re doing high-throughput bulk writes, complex read-only aggregation, or working with genuinely schemaless data, as covered in the “When Not to Reach for Mongoose” section above.

Q. Why did my password-hashing hook not run on an update?

A. pre('save') hooks only fire on the document API (save(), create()). Query-style operations like updateOne() and findOneAndUpdate() skip document middleware entirely unless you register a hook specifically for that operation (e.g., pre('findOneAndUpdate', ...)). See the CRUD Operations section above for the full explanation.

Q. How do I debug a slow Mongoose query?

A. Call .explain('executionStats') on the query to see whether MongoDB is using an index or falling back to a collection scan (COLLSCAN), and check .maxTimeMS() behavior under load. If the slowdown is from populate(), profile whether an aggregation $lookup (shown in the Population section) resolves it in fewer round trips.