mongoose

Mongoose MongoDB ODM

weekly downloads3.9M

versionv9.2.1

licenseMIT

categorydatabase

mongodbdocumentmodelschemadatabaseodmdatadatastorequerynosqlormdb

Overview

Mongoose is an Object Document Mapper (ODM) that provides a schema-based abstraction layer over MongoDB for Node.js applications. With over 3.9 million weekly downloads, it has become the de facto standard for MongoDB development in JavaScript ecosystems. While MongoDB is schema-less by design, Mongoose adds structure through schemas, enabling type safety, validation, and complex business logic that would otherwise require manual implementation.

The library bridges the gap between MongoDB's flexible document model and JavaScript's object-oriented patterns. It translates high-level JavaScript operations into MongoDB commands, allowing developers to define models with strict schemas, validation rules, and relationships between documents. This approach prevents common data integrity issues and makes codebases more maintainable as applications scale.

Mongoose is particularly valuable for teams building production applications that need predictable data structures, automated validation, and middleware hooks for business logic. It provides features like virtual properties for computed fields, population for pseudo-JOIN operations between collections, and a chainable query API that simplifies complex data retrieval. The library supports modern JavaScript features including native Promises, async/await, and has alpha support for Deno as of version 6.8.0.

Developers choose Mongoose when they need more structure than raw MongoDB drivers provide but want to maintain the flexibility of a NoSQL database. It's commonly used in Express.js applications, RESTful APIs, and full-stack JavaScript projects where data modeling and validation are critical concerns.

Quick Start

typescript

const mongoose = require('mongoose');

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

// Define schema with validation
const userSchema = new mongoose.Schema({
  email: {
    type: String,
    required: true,
    unique: true,
    lowercase: true,
    validate: {
      validator: (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v),
      message: 'Invalid email format'
    }
  },
  password: { type: String, required: true, minlength: 8 },
  firstName: { type: String, required: true },
  lastName: { type: String, required: true },
  createdAt: { type: Date, default: Date.now }
});

// Virtual property (not stored in DB)
userSchema.virtual('fullName').get(function() {
  return `${this.firstName} ${this.lastName}`;
});

// Middleware: hash password before saving
userSchema.pre('save', async function(next) {
  if (this.isModified('password')) {
    const bcrypt = require('bcrypt');
    this.password = await bcrypt.hash(this.password, 10);
  }
  next();
});

// Instance method for password verification
userSchema.methods.comparePassword = async function(candidatePassword) {
  const bcrypt = require('bcrypt');
  return bcrypt.compare(candidatePassword, this.password);
};

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

// Create and save a user
const user = new User({
  email: 'john@example.com',
  password: 'securepass123',
  firstName: 'John',
  lastName: 'Doe'
});

await user.save(); // Password automatically hashed via middleware
console.log(user.fullName); // "John Doe" from virtual property

// Query with Mongoose API
const foundUser = await User.findOne({ email: 'john@example.com' });
const isValid = await foundUser.comparePassword('securepass123');
console.log('Password valid:', isValid);

Use Cases

Building RESTful APIs with validated data models: Define schemas with built-in validation rules, required fields, and type constraints to ensure API endpoints receive and store properly structured data. Mongoose automatically validates documents before saving, preventing invalid data from reaching the database.

Implementing user authentication systems: Create User models with password hashing middleware, email validation, and virtual properties for computed fields like full names. Pre-save hooks can automatically hash passwords before storage, while instance methods can verify credentials during login.

Managing relationships between collections: Use population to reference documents across collections, such as linking blog posts to authors or orders to customers. Virtual populate enables pseudo-JOIN operations without storing redundant data, maintaining MongoDB's document-oriented design while providing relational-like queries.

Building multi-tenant SaaS applications: Define discriminators to create specialized models that inherit from base schemas, allowing different document types within the same collection. This enables flexible data modeling where related entities share common fields but have type-specific properties.

Implementing complex business logic with middleware: Execute validation, transformation, or logging logic at specific lifecycle stages using pre and post hooks. This centralizes business rules in the model layer, ensuring consistent behavior across the application regardless of where documents are created or modified.

Pros & Cons

Pros

+Comprehensive schema validation with custom validators, defaults, and type casting eliminates manual data validation code
+Powerful middleware system enables centralized business logic through pre/post hooks on save, validate, remove, and query operations
+Extensive query builder with chainable methods, population for document references, and virtual properties simplifies complex data operations
+Mature ecosystem with extensive documentation, TypeScript support, and large community with 3.9M+ weekly downloads
+Plugin architecture allows code reuse across schemas with built-in plugins for timestamps, soft deletes, and other common patterns

Cons

−Adds abstraction overhead that can impact performance compared to native MongoDB driver, especially for high-throughput operations
−Learning curve for developers new to ODM patterns, particularly around middleware execution order and population performance implications
−Schema rigidity can become a limitation when MongoDB's schema-less flexibility is actually needed for highly dynamic data structures
−Large bundle size (the package and dependencies add significant weight) may be overkill for simple CRUD applications
−Mongoose-specific query syntax differs from native MongoDB queries, creating vendor lock-in and making migration to other tools more difficult

Alternatives

prismav7.4.0

Prisma is an open-source database toolkit. It includes a JavaScript/TypeScript ORM for Node.js, migrations and a modern GUI to view and edit the data in your database. You can use Prisma in new projects or add it to an existing one.

databaseCLIORM

7.8M / week

typeormv0.3.28

Data-Mapper ORM for TypeScript and ES2021+. Supports MySQL/MariaDB, PostgreSQL, MS SQL Server, Oracle, SAP HANA, SQLite, MongoDB databases.

database

3.2M / week

Comparisons

mongoose vs prisma

database

Install

bash

npm install mongoose

bash

pnpm add mongoose

bash

bun add mongoose

Overview

Quick Start

typescript

const mongoose = require('mongoose');

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

// Define schema with validation
const userSchema = new mongoose.Schema({
  email: {
    type: String,
    required: true,
    unique: true,
    lowercase: true,
    validate: {
      validator: (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v),
      message: 'Invalid email format'
    }
  },
  password: { type: String, required: true, minlength: 8 },
  firstName: { type: String, required: true },
  lastName: { type: String, required: true },
  createdAt: { type: Date, default: Date.now }
});

// Virtual property (not stored in DB)
userSchema.virtual('fullName').get(function() {
  return `${this.firstName} ${this.lastName}`;
});

// Middleware: hash password before saving
userSchema.pre('save', async function(next) {
  if (this.isModified('password')) {
    const bcrypt = require('bcrypt');
    this.password = await bcrypt.hash(this.password, 10);
  }
  next();
});

// Instance method for password verification
userSchema.methods.comparePassword = async function(candidatePassword) {
  const bcrypt = require('bcrypt');
  return bcrypt.compare(candidatePassword, this.password);
};

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

// Create and save a user
const user = new User({
  email: 'john@example.com',
  password: 'securepass123',
  firstName: 'John',
  lastName: 'Doe'
});

await user.save(); // Password automatically hashed via middleware
console.log(user.fullName); // "John Doe" from virtual property

// Query with Mongoose API
const foundUser = await User.findOne({ email: 'john@example.com' });
const isValid = await foundUser.comparePassword('securepass123');
console.log('Password valid:', isValid);

Use Cases

Pros & Cons

Pros

+Comprehensive schema validation with custom validators, defaults, and type casting eliminates manual data validation code
+Powerful middleware system enables centralized business logic through pre/post hooks on save, validate, remove, and query operations
+Extensive query builder with chainable methods, population for document references, and virtual properties simplifies complex data operations
+Mature ecosystem with extensive documentation, TypeScript support, and large community with 3.9M+ weekly downloads
+Plugin architecture allows code reuse across schemas with built-in plugins for timestamps, soft deletes, and other common patterns

Cons

−Adds abstraction overhead that can impact performance compared to native MongoDB driver, especially for high-throughput operations
−Learning curve for developers new to ODM patterns, particularly around middleware execution order and population performance implications
−Schema rigidity can become a limitation when MongoDB's schema-less flexibility is actually needed for highly dynamic data structures
−Large bundle size (the package and dependencies add significant weight) may be overkill for simple CRUD applications
−Mongoose-specific query syntax differs from native MongoDB queries, creating vendor lock-in and making migration to other tools more difficult