MongoDB with Mongoose ODM - schemas, models, queries, aggregation, indexes, TypeScript typing, connection management
Quick Guide: Use Mongoose as the ODM for MongoDB. Define schemas with automatic TypeScript inference, use
lean()for read-only queries, prefer embedding over referencing for co-accessed data, place$matchearly in aggregation pipelines, and always define indexes to match your query patterns.
<critical_requirements>
All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,
import type, named constants)
(You MUST define Mongoose middleware (pre/post hooks) BEFORE calling model() -- hooks registered after model compilation are silently ignored)
{ session } to EVERY operation inside a transaction -- missing session causes operations to run outside the transaction)(You MUST use .lean() for read-only queries that send results directly to API responses -- skipping lean wastes 3x memory on hydration overhead)
(You MUST use 127.0.0.1 instead of localhost in connection strings -- Node.js 18+ prefers IPv6 and localhost can cause connection timeouts)
(You MUST NOT use findOneAndUpdate / updateOne and expect save middleware to fire -- only save() and create() trigger document middleware)
</critical_requirements>
Auto-detection: MongoDB, Mongoose, mongoose.connect, Schema, model, ObjectId, populate, aggregate, $match, $group, $lookup, lean, HydratedDocument, InferSchemaType, MongoClient, Atlas
When to use:
Key patterns covered:
When NOT to use:
Detailed Resources:
Core Patterns:
Query Patterns:
Aggregation:
Advanced Patterns:
Indexing:
MongoDB is a document database. Mongoose provides schema-based modeling on top of it. The core principle: data that is accessed together should be stored together.
Core principles:
.lean() for read-only queries. It returns plain objects (3x less memory) instead of full Mongoose documents.When to use MongoDB / Mongoose:
Establish a single connection at startup with named constants for pool/timeout config and environment variables for credentials. See examples/core.md for full examples including connection events and graceful shutdown.
const connection = await mongoose.connect(process.env.MONGODB_URI!, {
maxPoolSize: POOL_SIZE_MAX,
minPoolSize: POOL_SIZE_MIN,
serverSelectionTimeoutMS: SERVER_SELECTION_TIMEOUT_MS,
socketTimeoutMS: SOCKET_TIMEOUT_MS,
retryWrites: true,
retryReads: true,
});
Let Mongoose infer types from the schema definition. Use explicit interfaces only when adding methods, statics, or virtuals. See examples/core.md for full typing examples with HydratedDocument, InferSchemaType, and generic parameters.
// Preferred: automatic type inference
const userSchema = new Schema(
{
name: { type: String, required: true, trim: true },
email: { type: String, required: true, unique: true, lowercase: true },
role: {
type: String,
enum: ["admin", "user", "moderator"] as const,
default: "user",
},
},
{ timestamps: true },
);
const User = model("User", userSchema);
// For methods/statics/virtuals: explicit interfaces with Schema generics
const userSchema = new Schema<IUser, UserModel, IUserMethods, {}, IUserVirtuals>({ ... });
Use .lean() for read-only queries, save() when middleware must fire, findByIdAndUpdate with { runValidators: true } for direct updates. See examples/core.md for full CRUD examples.
const user = await User.findById(id).lean(); // read-only, 3x less memory
await User.insertMany(users, { ordered: false }); // bulk insert
await User.findByIdAndUpdate(id, update, { new: true, runValidators: true }); // direct update
Use comparison/logical operators for filters, .populate() with field selection and limits. See examples/queries.md for dynamic query builders, cursor-based pagination, and populate patterns.
const post = await Post.findById(id)
.populate("author", "name email")
.populate({
path: "comments",
options: { sort: { createdAt: -1 }, limit: 10 },
})
.lean();
Add custom error messages, regex validation, and array-level validators. See examples/core.md for complete validation examples.