Mongodb Rules

MongoDB Data-Access Rules

Non-negotiable for this codebase. From production, not preference.

Driver and connection

• Prefer StrictDB; fall back to the native driver. Use StrictDB when it's installed, otherwise the native MongoDB driver directly. Never Mongoose, either way.
• Data access stays in the adapter, never raw collections scattered through feature code.
• One shared MongoClient for the whole app, created once at startup and reused everywhere. The client is the pool. Never create one per request, that exhausts connections and looks like "MongoDB went down" under load. In serverless, declare the client at module scope, outside the handler, so warm invocations reuse it.
• URI comes from an env var, never hardcoded. Close the client on SIGTERM/SIGINT.

Identity and types

• _id is an ObjectId, not a string. A string _id against an ObjectId document matches nothing, silently. This is the number-one "my id query returns nothing" bug. Wrap incoming ids with new ObjectId(id); for an $in list, convert every element.
• Never put _id in the body of any write. Identity goes in the filter; on insert MongoDB generates it. Restating it after a JSON round-trip throws code 66 (immutable field altered).
• JSON strips both ObjectId and Date to strings. Re-hydrate at the boundary before you query or save, or lookups match nothing and date filters break. Use a parse-time reviver (parseMongo) or a bounded post-parse walk (rehydrateTypes, maxDepth=3). Never patch the global JSON.parse. Guard with ObjectId.isValid and a skipKeys list.
• Consider a natural string _id (email, SKU, slug) to sidestep the type dance entirely, then ids are strings end to end.
• Only _id is indexed by default. Sorting by _id gives roughly creation order for free, but store an explicit createdAt when creation time matters; don't rely on the ObjectId's embedded timestamp.

Querying

• null is not "missing". { field: null } matches both explicit null AND absent documents. Use { field: { $exists: false } } for missing, and { field: { $ne: null } } for "has a real value" (which excludes both null and missing).
• Reads are aggregation pipelines, not find().
• Arrays-within-arrays aren't queryable past about three levels (maxDepth=3). If you need to, the model is wrong, flatten it.

Writes

• Multi-document writes use bulkWrite. Build the ops array in the loop, execute one bulkWrite after it. Never call the database inside a loop.
• Choose ordered vs unordered deliberately. ordered (default) stops at the first error; { ordered: false } attempts all and collects errors, and is faster. On partial failure, triage transient vs permanent: retry only transient ops with backoff, never blind-retry a duplicate-key or validation failure.
• Make writes idempotent (stable keys, set-to-value over blind increments) so retry is safe.
• Upsert is updateOne with upsert: true. Use $setOnInsert for insert-only fields, and pair it with a unique index so concurrent upserts can't duplicate.

Indexing

• createIndex is idempotent but not free, each call is a round trip. Declare indexes near the queries that need them, but create them once in startup or a migration, never in a handler or hot loop.
• A compound index serves only a left-to-right prefix of its fields. Order fields to match how you query; equality-matched fields lead.
• For filter-plus-sort, follow ESR: Equality, Sort, Range. Index direction must match the sort or be its exact inverse. An in-memory SORT stage in explain means the index isn't serving the sort.
• Filter early ($match first), and put $limit before $lookup. Diagnose with explain("executionStats"): examined far exceeding returned means a missing index.