mongodb

mongodb Best Practices

MongoDB's flexible schema is a superpower, but with great power comes great responsibility. This guide cuts through the noise to give you the definitive, opinionated best practices for building robust, high-performance applications with MongoDB. Follow these rules to avoid common pitfalls and leverage MongoDB effectively.

1. Data Modeling: Store Data Accessed Together, Together

The cardinal rule: embed data that is accessed together within a single document. This minimizes joins and maximizes read performance. Use referencing for many-to-many relationships or when embedded data would exceed the 16MB document limit or grow unboundedly.

1.1. Embed for Read Performance

✅ GOOD: Embed tightly coupled, frequently accessed data.

// User document with embedded preferences
{
    "_id": ObjectId("656e2c0e8a7b9c1d2e3f4a5b"),
    "username": "johndoe",
    "email": "[email protected]",
    "preferences": {
        "theme": "dark",
        "notifications": {
            "email": true,
            "sms": false
        }
    }
}

❌ BAD: Separating tightly coupled data into multiple collections, forcing $lookup for common reads.

// User document
{ "_id": ObjectId("656e2c0e8a7b9c1d2e3f4a5b"), "username": "johndoe", "email": "[email protected]" }
// UserPreferences document (separate collection)
{ "_id": ObjectId("656e2c0e8a7b9c1d2e3f4a5c"), "userId": ObjectId("656e2c0e8a7b9c1d2e3f4a5b"), "theme": "dark", "notifications": { "email": true, "sms": false } }
// Requires a join to get user with preferences.

1.2. Reference for Unbounded Growth or Many-to-Many

Use referencing when a sub-document array could grow indefinitely (e.g., comments on a blog post) or when documents are frequently updated independently.

✅ GOOD: Reference comments from a blog post.

// Post document
{
    "_id": ObjectId("post123"),
    "title": "My Awesome Post",
    "content": "...",
    "authorId": ObjectId("user456"),
    "commentCount": 5 // Denormalized for quick access
}
// Comment document (separate collection)
{
    "_id": ObjectId("comment789"),
    "postId": ObjectId("post123"),
    "authorId": ObjectId("user987"),
    "text": "Great post!",
    "createdAt": ISODate("2025-01-01T10:00:00Z")
}

❌ BAD: Embedding an unbounded array of comments within the post document. This risks exceeding the 16MB document limit and makes updates inefficient.

// Post document with embedded comments
{
    "_id": ObjectId("post123"),
    "title": "My Awesome Post",
    "content": "...",
    "authorId": ObjectId("user456"),
    "comments": [ // This array can grow indefinitely!
        {"authorId": ObjectId("user987"), "text": "Great post!", "createdAt": ISODate("2025-01-01T10:00:00Z")},
        {"authorId": ObjectId("user111"), "text": "I agree!", "createdAt": ISODate("2025-01-01T10:05:00Z")}
    ]
}