Mongodb Mongoose
Optimized for current MongoDB server releases, Mongoose 8.x+, Node.js 22+, and TypeScript 5.5+.
Comprehensive guidance for MongoDB database design, Mongoose ODM patterns, and Atlas integration for Node.js/Next.js applications.
- Leverage native parallel subagent dispatch and 200k+ context windows where available.
When to Use This Skill
Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.
- Designing MongoDB schemas and data models
- Building Mongoose models with validation and middleware
- Implementing the repository pattern for data access
- Writing aggregation pipelines for complex queries
- Managing MongoDB Atlas connections and configuration
- Integrating MongoDB with Next.js API routes
- Database migration strategies
Cross-Client Portability
This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.
- GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the
workflow in project instructions when folder discovery is unavailable.
- Claude Code: keep the folder in a local skills directory or a compatible plugin source.
- Codex: install or sync the folder into
$CODEX_HOME/skills/mongodb-mongoose and restart Codex after major changes.
MCP Availability And Fallback
Preferred MCP Server: MongoDB MCP
- Fallback prompt: "Use the Mongodb Mongoose skill without MCP. Follow the documented local or manual fallback, show the selected tool surface, and report the verification evidence."
- Use
mongosh, MongoDB Atlas UI, local schema files, and Mongoose model inspection when the MCP server is unavailable.
- Validate indexes, queries, and aggregation pipelines against a local or staging database before finalizing changes.
- Do not claim an MCP operation was used when the active host does not expose it.
Anti-Patterns
- Modeling documents like normalized tables by default: MongoDB performance depends on query-driven shape, not relational purity.
- Returning full hydrated documents for every request: Over-fetching and hydration overhead accumulate quickly in API paths.
- Adding middleware without write-path tests: Hooks can silently change create, update, and migration behavior.
Verification Protocol
Before claiming "skill applied successfully":
- Pass/fail: The Mongodb Mongoose implementation names the target runtime, framework version, and affected files.
- Pass/fail: Build, lint, test, or equivalent local validation is run for the changed surface.
- Pass/fail: Edge cases for errors, dependency drift, and environment differences are addressed or explicitly out of scope.
- Pressure-test scenario: Apply the workflow to a change that passes happy-path tests but fails one boundary condition.
- Success metric: Zero untested success claims; every implementation claim maps to a command or artifact.
Before and After Example
// Before
const recipes = await Recipe.find({ author: userId }).populate('author');
// After
const recipes = await Recipe.find({ author: userId, isPublished: true })
.select({ title: 1, slug: 1, createdAt: 1 })
.sort({ createdAt: -1 })
.lean();
Narrows the query shape, avoids unnecessary hydration, and aligns the result with the view model actually needed.
Schema Design
Data Modeling Principles
- Embed when data is accessed together and has a 1:few relationship
- Reference when data is accessed independently or has a 1:many/many:many relationship
- Design schemas around query patterns, not normalized relational models
- Use denormalization strategically for read performance
Mongoose Model Pattern
import mongoose from 'mongoose';
const recipeSchema = new mongoose.Schema({
title: {
type: String,
required: [true, 'Title is required'],
trim: true,
maxlength: [200, 'Title cannot exceed 200 characters'],
index: true,
},
slug: {
type: String,
unique: true,
lowercase: true,
},
ingredients: [{
name: { type: String, required: true },
amount: { type: Number, required: true },
unit: { type: String, enum: ['g', 'kg', 'ml', 'l', 'cup', 'tbsp', 'tsp', 'piece'] },
}],
author: {
type: mongoose.Schema.Types.ObjectId,
ref: 'User',
required: true,
index: true,
},
tags: [{ type: String, lowercase: true, trim: true }],
isPublished: { type: Boolean, default: false },
}, {
timestamps: true,
toJSON: { virtuals: true },
toObject: { virtuals: true },
});
// Indexes for common queries
recipeSchema.index({ title: 'text', tags: 'text' });
recipeSchema.index({ author: 1, createdAt: -1 });
// Virtual fields
recipeSchema.virtual('ingredientCount').get(function() {
return this.ingredients.length;
});
// Pre-save middleware
recipeSchema.pre('save', function(next) {
if (this.isModified('title')) {
this.slug = this.title.toLowerCase().replace(/[^a-z0-9]+/g, '-');
}
next();
});
export const Recipe = mongoose.models.Recipe || mongoose.model('Recipe', recipeSchema);
Schema Best Practices
- Always define
required, type, and validation rules
- Use
timestamps: true for automatic createdAt/updatedAt
- Add indexes for frequently queried fields
- Use
enum for fields with fixed values
- Define virtuals for computed properties
- Use middleware (pre/post hooks) for side effects
Repository Pattern
class RecipeRepository {
async findAll(filter = {}, options = {}) {
const { page = 1, limit = 20, sort = '-createdAt', populate = '' } = options;
const skip = (page - 1) * limit;
const [recipes, total] = await Promise.all([
Recipe.find(filter)
.sort(sort)
.skip(skip)
.limit(limit)
.populate(populate)
.lean(),
Recipe.countDocuments(filter),
]);
return {
data: recipes,
pagination: {
page,
limit,
total,
pages: Math.ceil(total / limit),
},
};
}
async findById(id) {
return Recipe.findById(id).populate('author', 'name avatar').lean();
}
async create(data) {
const recipe = new Recipe(data);
return recipe.save();
}
async update(id, data) {
return Recipe.findByIdAndUpdate(id, data, {
new: true,
runValidators: true,
});
}
async delete(id) {
return Recipe.findByIdAndDelete(id);
}
async search(query, options = {}) {
return this.findAll(
{ $text: { $search: query } },
{ ...options, sort: { score: { $meta: 'textScore' } } }
);
}
}
export const recipeRepository = new RecipeRepository();
Aggregation Pipelines
Common Patterns
// Group recipes by tag with counts
const tagStats = await Recipe.aggregate([
{ $match: { isPublished: true } },
{ $unwind: '$tags' },
{ $group: { _id: '$tags', count: { $sum: 1 } } },
{ $sort: { count: -1 } },
{ $limit: 20 },
]);
// Author statistics with lookup
const authorStats = await Recipe.aggregate([
{ $group: {
_id: '$author',
recipeCount: { $sum: 1 },
avgRating: { $avg: '$rating' },
}},
{ $lookup: {
from: 'users',
localField: '_id',
foreignField: '_id',
as: 'authorInfo',
}},
{ $unwind: '$authorInfo' },
{ $project: {
name: '$authorInfo.name',
recipeCount: 1,
avgRating: { $round: ['$avgRating', 1] },
}},
{ $sort: { recipeCount: -1 } },
]);
// Date-based analytics
const monthlyRecipes = await Recipe.aggregate([
{ $match: { createdAt: { $gte: new Date('2024-01-01') } } },
{ $group: {
_id: { $dateToString: { format: '%Y-%m', date: '$createdAt' } },
count: { $sum: 1 },
}},
{ $sort: { _id: 1 } },
]);
Atlas Connection
Connection Setup (Next.js)
import mongoose from 'mongoose';
const MONGODB_URI = process.env.MONGODB_URI;
if (!MONGODB_URI) {
throw new Error('MONGODB_URI environment variable is not defined');
}
let cached = global.mongoose;
if (!cached) {
cached = global.mongoose = { conn: null, promise: null };
}
export async function connectDB() {
if (cached.conn) return cached.conn;
if (!cached.promise) {
cached.promise = mongoose.connect(MONGODB_URI, {
bufferCommands: false,
});
}
cached.conn = await cached.promise;
return cached.conn;
}
Connection Best Practices
- Cache connection in development to prevent multiple connections
- Use
bufferCommands: false for explicit error handling
- Set connection pool size via
maxPoolSize for production
- Use Atlas connection string with
retryWrites=true&w=majority
Migration Strategies
Document Versioning
const userSchema = new mongoose.Schema({
schemaVersion: { type: Number, default: 2 },
// ... fields
});
userSchema.pre('save', function(next) {
if (this.schemaVersion < 2) {
// Migrate old fields to new format
this.schemaVersion = 2;
}
next();
});
Batch Migration Script
async function migrateUsers() {
const batchSize = 100;
let processed = 0;
let batch;
do {
batch = await User.find({ schemaVersion: { $lt: 2 } }).limit(batchSize);
for (const user of batch) {
user.schemaVersion = 2;
await user.save();
processed++;
}
console.log(`Migrated ${processed} users`);
} while (batch.length === batchSize);
}
Performance Tips
- Use
.lean() for read-only queries (returns plain objects, 5-10x faster)
- Use
.select() to return only needed fields
- Create compound indexes matching your query patterns
- Use
$project early in aggregation to reduce working set
- Avoid
$lookup in high-frequency queries; denormalize instead
- Use
explain() to analyze query performance
Troubleshooting
| Issue |
Solution |
| Slow queries |
Add indexes, use .lean(), check with explain() |
| Connection timeouts |
Check Atlas network access, increase pool size |
| Validation errors |
Review schema constraints, check middleware order |
| Duplicate key errors |
Ensure unique indexes, handle with try/catch |
| Memory issues |
Use cursors for large datasets, limit batch sizes |
Common Pitfalls
- Modeling data like a normalized relational schema by default: MongoDB performance depends on query-driven document shape, not tables-first design.
- Returning full hydrated documents everywhere: Hydration and over-fetching add cost when a lean projection would do.
- Adding middleware without explicit write-path tests: Hooks can silently change behavior in create, update, and migration flows.
References & Resources
Documentation
Scripts
- Seed Database — Zero-dependency MongoDB seeding script with sample recipe data
Examples
- Recipe API Example — Complete Mongoose + Next.js Recipe CRUD API with models, routes, and validation
Related Skills
- javascript-development: Use it when the workflow also needs modern JavaScript and TypeScript application code.
- nextjs-development: Use it when the workflow also needs Next.js App Router and server-first React patterns.
- sql-development: Use it when the workflow also needs SQL query, schema, and performance tuning work.
- code-quality: Use it when the workflow also needs two-stage review (spec compliance first, then code quality), maintainability, and refactoring guidance.
1---
2name: mongodb-mongoose
3version: "2.0"
4last_updated: 2026-09-08
5tags: [mongodb, mongoose, development, testing, quality]
6description: "MongoDB with Mongoose — schemas, models, aggregation pipelines, migrations, and Atlas connections. Use when designing collections, writing queries, or integrating MongoDB into Node.js/Next.js apps."
7metadata:
8 source: https://skillmd.com/skills/practicalswan/mongodb-mongoose
9---
10
11# Mongodb Mongoose
12
13> Optimized for current MongoDB server releases, Mongoose 8.x+, Node.js 22+, and TypeScript 5.5+.
14
15Comprehensive guidance for MongoDB database design, Mongoose ODM patterns, and Atlas integration for Node.js/Next.js applications.
16
17- Leverage native parallel subagent dispatch and 200k+ context windows where available.
18
19
20## When to Use This Skill
21
22Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.
23
24- Designing MongoDB schemas and data models
25- Building Mongoose models with validation and middleware
26- Implementing the repository pattern for data access
27- Writing aggregation pipelines for complex queries
28- Managing MongoDB Atlas connections and configuration
29- Integrating MongoDB with Next.js API routes
30- Database migration strategies
31
32
33---
34
35<!-- MCP:START -->
36
37<!-- PORTABILITY:START -->
38## Cross-Client Portability
39
40This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.
41
42- GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the
43 workflow in project instructions when folder discovery is unavailable.
44- Claude Code: keep the folder in a local skills directory or a compatible plugin source.
45- Codex: install or sync the folder into
46 `$CODEX_HOME/skills/mongodb-mongoose` and restart Codex after major changes.
47
48<!-- PORTABILITY:END -->
49
50## MCP Availability And Fallback
51
52Preferred MCP Server: MongoDB MCP
53
54- Fallback prompt: "Use the Mongodb Mongoose skill without MCP. Follow the documented local or manual fallback, show the selected tool surface, and report the verification evidence."
55- Use `mongosh`, MongoDB Atlas UI, local schema files, and Mongoose model inspection when the MCP server is unavailable.
56- Validate indexes, queries, and aggregation pipelines against a local or staging database before finalizing changes.
57- Do not claim an MCP operation was used when the active host does not expose it.
58
59<!-- MCP:END -->
60
61## Anti-Patterns
62
63- Modeling documents like normalized tables by default: MongoDB performance depends on query-driven shape, not relational purity.
64- Returning full hydrated documents for every request: Over-fetching and hydration overhead accumulate quickly in API paths.
65- Adding middleware without write-path tests: Hooks can silently change create, update, and migration behavior.
66
67## Verification Protocol
68
69Before claiming "skill applied successfully":
70
711. Pass/fail: The Mongodb Mongoose implementation names the target runtime, framework version, and affected files.
722. Pass/fail: Build, lint, test, or equivalent local validation is run for the changed surface.
733. Pass/fail: Edge cases for errors, dependency drift, and environment differences are addressed or explicitly out of scope.
744. Pressure-test scenario: Apply the workflow to a change that passes happy-path tests but fails one boundary condition.
755. Success metric: Zero untested success claims; every implementation claim maps to a command or artifact.
76
77## Before and After Example
78
79```javascript
80// Before
81const recipes = await Recipe.find({ author: userId }).populate('author');
82
83// After
84const recipes = await Recipe.find({ author: userId, isPublished: true })
85 .select({ title: 1, slug: 1, createdAt: 1 })
86 .sort({ createdAt: -1 })
87 .lean();
88```
89
90Narrows the query shape, avoids unnecessary hydration, and aligns the result with the view model actually needed.
91
92## Schema Design
93
94### Data Modeling Principles
95- **Embed** when data is accessed together and has a 1:few relationship
96- **Reference** when data is accessed independently or has a 1:many/many:many relationship
97- Design schemas around query patterns, not normalized relational models
98- Use denormalization strategically for read performance
99
100### Mongoose Model Pattern
101```javascript
102import mongoose from 'mongoose';
103
104const recipeSchema = new mongoose.Schema({
105 title: {
106 type: String,
107 required: [true, 'Title is required'],
108 trim: true,
109 maxlength: [200, 'Title cannot exceed 200 characters'],
110 index: true,
111 },
112 slug: {
113 type: String,
114 unique: true,
115 lowercase: true,
116 },
117 ingredients: [{
118 name: { type: String, required: true },
119 amount: { type: Number, required: true },
120 unit: { type: String, enum: ['g', 'kg', 'ml', 'l', 'cup', 'tbsp', 'tsp', 'piece'] },
121 }],
122 author: {
123 type: mongoose.Schema.Types.ObjectId,
124 ref: 'User',
125 required: true,
126 index: true,
127 },
128 tags: [{ type: String, lowercase: true, trim: true }],
129 isPublished: { type: Boolean, default: false },
130}, {
131 timestamps: true,
132 toJSON: { virtuals: true },
133 toObject: { virtuals: true },
134});
135
136// Indexes for common queries
137recipeSchema.index({ title: 'text', tags: 'text' });
138recipeSchema.index({ author: 1, createdAt: -1 });
139
140// Virtual fields
141recipeSchema.virtual('ingredientCount').get(function() {
142 return this.ingredients.length;
143});
144
145// Pre-save middleware
146recipeSchema.pre('save', function(next) {
147 if (this.isModified('title')) {
148 this.slug = this.title.toLowerCase().replace(/[^a-z0-9]+/g, '-');
149 }
150 next();
151});
152
153export const Recipe = mongoose.models.Recipe || mongoose.model('Recipe', recipeSchema);
154```
155
156### Schema Best Practices
157- Always define `required`, `type`, and validation rules
158- Use `timestamps: true` for automatic `createdAt`/`updatedAt`
159- Add indexes for frequently queried fields
160- Use `enum` for fields with fixed values
161- Define virtuals for computed properties
162- Use middleware (pre/post hooks) for side effects
163
164---
165
166## Repository Pattern
167
168```javascript
169class RecipeRepository {
170 async findAll(filter = {}, options = {}) {
171 const { page = 1, limit = 20, sort = '-createdAt', populate = '' } = options;
172 const skip = (page - 1) * limit;
173
174 const [recipes, total] = await Promise.all([
175 Recipe.find(filter)
176 .sort(sort)
177 .skip(skip)
178 .limit(limit)
179 .populate(populate)
180 .lean(),
181 Recipe.countDocuments(filter),
182 ]);
183
184 return {
185 data: recipes,
186 pagination: {
187 page,
188 limit,
189 total,
190 pages: Math.ceil(total / limit),
191 },
192 };
193 }
194
195 async findById(id) {
196 return Recipe.findById(id).populate('author', 'name avatar').lean();
197 }
198
199 async create(data) {
200 const recipe = new Recipe(data);
201 return recipe.save();
202 }
203
204 async update(id, data) {
205 return Recipe.findByIdAndUpdate(id, data, {
206 new: true,
207 runValidators: true,
208 });
209 }
210
211 async delete(id) {
212 return Recipe.findByIdAndDelete(id);
213 }
214
215 async search(query, options = {}) {
216 return this.findAll(
217 { $text: { $search: query } },
218 { ...options, sort: { score: { $meta: 'textScore' } } }
219 );
220 }
221}
222
223export const recipeRepository = new RecipeRepository();
224```
225
226---
227
228## Aggregation Pipelines
229
230### Common Patterns
231
232```javascript
233// Group recipes by tag with counts
234const tagStats = await Recipe.aggregate([
235 { $match: { isPublished: true } },
236 { $unwind: '$tags' },
237 { $group: { _id: '$tags', count: { $sum: 1 } } },
238 { $sort: { count: -1 } },
239 { $limit: 20 },
240]);
241
242// Author statistics with lookup
243const authorStats = await Recipe.aggregate([
244 { $group: {
245 _id: '$author',
246 recipeCount: { $sum: 1 },
247 avgRating: { $avg: '$rating' },
248 }},
249 { $lookup: {
250 from: 'users',
251 localField: '_id',
252 foreignField: '_id',
253 as: 'authorInfo',
254 }},
255 { $unwind: '$authorInfo' },
256 { $project: {
257 name: '$authorInfo.name',
258 recipeCount: 1,
259 avgRating: { $round: ['$avgRating', 1] },
260 }},
261 { $sort: { recipeCount: -1 } },
262]);
263
264// Date-based analytics
265const monthlyRecipes = await Recipe.aggregate([
266 { $match: { createdAt: { $gte: new Date('2024-01-01') } } },
267 { $group: {
268 _id: { $dateToString: { format: '%Y-%m', date: '$createdAt' } },
269 count: { $sum: 1 },
270 }},
271 { $sort: { _id: 1 } },
272]);
273```
274
275---
276
277## Atlas Connection
278
279### Connection Setup (Next.js)
280```javascript
281import mongoose from 'mongoose';
282
283const MONGODB_URI = process.env.MONGODB_URI;
284
285if (!MONGODB_URI) {
286 throw new Error('MONGODB_URI environment variable is not defined');
287}
288
289let cached = global.mongoose;
290if (!cached) {
291 cached = global.mongoose = { conn: null, promise: null };
292}
293
294export async function connectDB() {
295 if (cached.conn) return cached.conn;
296
297 if (!cached.promise) {
298 cached.promise = mongoose.connect(MONGODB_URI, {
299 bufferCommands: false,
300 });
301 }
302
303 cached.conn = await cached.promise;
304 return cached.conn;
305}
306```
307
308### Connection Best Practices
309- Cache connection in development to prevent multiple connections
310- Use `bufferCommands: false` for explicit error handling
311- Set connection pool size via `maxPoolSize` for production
312- Use Atlas connection string with `retryWrites=true&w=majority`
313
314---
315
316## Migration Strategies
317
318### Document Versioning
319```javascript
320const userSchema = new mongoose.Schema({
321 schemaVersion: { type: Number, default: 2 },
322 // ... fields
323});
324
325userSchema.pre('save', function(next) {
326 if (this.schemaVersion < 2) {
327 // Migrate old fields to new format
328 this.schemaVersion = 2;
329 }
330 next();
331});
332```
333
334### Batch Migration Script
335```javascript
336async function migrateUsers() {
337 const batchSize = 100;
338 let processed = 0;
339 let batch;
340
341 do {
342 batch = await User.find({ schemaVersion: { $lt: 2 } }).limit(batchSize);
343 for (const user of batch) {
344 user.schemaVersion = 2;
345 await user.save();
346 processed++;
347 }
348 console.log(`Migrated ${processed} users`);
349 } while (batch.length === batchSize);
350}
351```
352
353---
354
355## Performance Tips
356
357- Use `.lean()` for read-only queries (returns plain objects, 5-10x faster)
358- Use `.select()` to return only needed fields
359- Create compound indexes matching your query patterns
360- Use `$project` early in aggregation to reduce working set
361- Avoid `$lookup` in high-frequency queries; denormalize instead
362- Use `explain()` to analyze query performance
363
364## Troubleshooting
365
366| Issue | Solution |
367|-------|----------|
368| Slow queries | Add indexes, use `.lean()`, check with `explain()` |
369| Connection timeouts | Check Atlas network access, increase pool size |
370| Validation errors | Review schema constraints, check middleware order |
371| Duplicate key errors | Ensure unique indexes, handle with try/catch |
372| Memory issues | Use cursors for large datasets, limit batch sizes |
373
374---
375
376## Common Pitfalls
377
378- Modeling data like a normalized relational schema by default: MongoDB performance depends on query-driven document shape, not tables-first design.
379- Returning full hydrated documents everywhere: Hydration and over-fetching add cost when a lean projection would do.
380- Adding middleware without explicit write-path tests: Hooks can silently change behavior in create, update, and migration flows.
381
382## References & Resources
383
384### Documentation
385- [Aggregation Reference](./references/aggregation-reference.md) — Pipeline stages, accumulator operators, and common aggregation recipes
386- [Indexing Strategies](./references/indexing-strategies.md) — Index types, ESR rule, compound indexes, and performance analysis
387
388### Scripts
389- [Seed Database](./scripts/seed-database.js) — Zero-dependency MongoDB seeding script with sample recipe data
390
391### Examples
392- [Recipe API Example](./examples/recipe-api-example.md) — Complete Mongoose + Next.js Recipe CRUD API with models, routes, and validation
393
394---
395
396## Related Skills
397
398- [javascript-development](../javascript-development/SKILL.md): Use it when the workflow also needs modern JavaScript and TypeScript application code.
399- [nextjs-development](../nextjs-development/SKILL.md): Use it when the workflow also needs Next.js App Router and server-first React patterns.
400- [sql-development](../sql-development/SKILL.md): Use it when the workflow also needs SQL query, schema, and performance tuning work.
401- [code-quality](../code-quality/SKILL.md): Use it when the workflow also needs two-stage review (spec compliance first, then code quality), maintainability, and refactoring guidance.