MongoDB Project

---
applyTo: "**/*.js, **/*.ts, **/models/**, **/schemas/**"
---

# MongoDB Development Instructions (2025)

_Last updated: October 2025_

- Always use the fetch tool to look up the latest MongoDB documentation: https://www.mongodb.com/docs
- Design document schemas with proper embedding vs. referencing strategy
- Use indexes strategically for query performance
- Implement proper validation with schema validation rules
- Use aggregation pipeline for complex queries
- Leverage MongoDB Atlas for cloud-hosted databases

**Core Principles:**

- Design schemas based on query patterns, not normalized tables
- Embed related data when read together, reference when independent
- Use atomic operations for data consistency
- Implement proper indexing strategy (compound, text, geospatial)
- Use transactions for multi-document operations when needed
- Follow naming conventions: camelCase for fields, lowercase for collections

**Schema Design:**

- Embed one-to-few relationships (arrays in documents)
- Reference one-to-many and many-to-many relationships
- Denormalize data when query performance is critical
- Use subdocuments for related data read together
- Implement proper data types (ObjectId, Date, ISODate)

**Querying:**

- Use MongoDB query operators: $eq, $gt, $in, $regex, etc.
- Implement aggregation pipeline for complex transformations
- Use $lookup for join-like operations
- Leverage $project for selecting specific fields
- Use cursor methods for pagination

**Indexing:**

- Create indexes on frequently queried fields
- Use compound indexes for multi-field queries
- Implement text indexes for full-text search
- Use partial indexes for filtered queries
- Monitor index usage with explain()

**Performance:**

- Use projection to return only needed fields
- Implement proper pagination with skip() and limit()
- Use bulk operations for multiple writes
- Consider caching frequently accessed data
- Monitor slow queries and optimize

**ODM:**

- Use Mongoose for schema validation and middleware
- Define proper schema types and validators
- Implement pre/post hooks for business logic
- Use virtuals for computed properties

**Summary:**

> For all MongoDB work, always use the fetch tool to look up the latest documentation from https://www.mongodb.com/docs. Design flexible, scalable document-based databases.