mongodb

Design MongoDB documents and indexes, build aggregation pipelines, and investigate query plans or transaction behavior.

SKILL.md

GitHub

MongoDB Document Database AI Skill Guide

Overview & Engine Architecture

MongoDB stores BSON documents in collections. Query paths drive compound index design; the aggregation pipeline is a staged computation graph. Replica sets provide durability via oplog replication; write concern and read concern define what “acknowledged” means—agents often treat majority as free insurance without counting voting data-bearing nodes.

Drivers (TLS, authSource, replicaSet)
    -> mongod replica set / sharded cluster
        -> collections + indexes (B-tree, partial, TTL, text)
        -> oplog -> secondary apply (async)
        -> change streams (resume tokens)

When to use / when not to

Use when

  • Access patterns favor embedded documents or flexible schema with controlled validation
  • You need aggregation analytics over documents without heavy cross-row joins
  • Designing indexes for find + sort + range on the same query shape

Do not use when

  • Multi-table joins and strict relational invariants dominate (@postgresql)
  • You need cross-document ACID on many collections routinely—transactions exist but cost throughput
  • Someone proposes storing secrets in client-side connection strings or disabling TLS on Atlas—refuse

Operational Capabilities & Agent Directives

  1. Connection safety: Full SRV URI with replicaSet, authSource, tls=true, and cert options for self-hosted; cap maxPoolSize; set serverSelectionTimeoutMS and connectTimeoutMS.
  2. Write concern: Default global majority is common; on P-S-A (primary + secondary + arbiter), w: majority can fail when the only data-bearing secondary is down—size replica sets for real redundancy or document degraded modes explicitly.
  3. Indexes: Equality fields first in compound index, then sort, then range; use partial and TTL indexes intentionally; avoid unbounded array growth.
  4. Migrations: Prefer additive schema + $jsonSchema validation; online index builds still load the cluster—build during low traffic with background equivalent (modern builds use index build coordination—check server version docs).
  5. Backup/restore: Point-in-time needs oplog/coordinated backup (Atlas, PBM, Cloud Manager). Do not restore a backup over prod without isolation; after non-majority periods, Percona PBM docs require restoring majority before relying on restored data.
  6. Auth: Database users with least privilege; readPreference secondary for analytics only when stale reads are acceptable.
  7. Exactly-once myth: Retryable writes prevent duplicate keys on idempotent ops but do not make downstream handlers exactly-once—use idempotent updateOne filters on business keys.

Production examples

Modeling + indexes

db.orders.createIndex({ customerId: 1, createdAt: -1 });
db.orders.createIndex(
  { status: 1 },
  { partialFilterExpression: { status: "open" } }
);

db.createCollection("orders", {
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["customerId", "status", "createdAt"],
      properties: {
        status: { enum: ["open", "paid", "cancelled"] },
        items: { bsonType: "array", maxItems: 50 }
      }
    }
  }
});

Aggregation with early $match

db.orders.aggregate([
  { $match: { createdAt: { $gte: ISODate("2026-01-01") }, status: "paid" } },
  { $group: { _id: "$customerId", revenue: { $sum: "$totalCents" } } },
  { $sort: { revenue: -1 } },
  { $limit: 50 }
]);

Idempotent upsert (handler safety)

db.events.updateOne(
  { eventId: "evt-1042" },
  { $setOnInsert: { payload: doc, createdAt: new Date() } },
  { upsert: true }
);

Explain

db.orders.find({ customerId: id, status: "open" })
  .sort({ createdAt: -1 })
  .explain("executionStats");

Backup agent URI (TLS + degraded ack — document explicitly)

mongodb://pbmuser:***@host1,host2,host3/?replicaSet=rs0&authSource=admin&tls=true&tlsCAFile=/etc/pbm/ca.pem&readConcernLevel=local&w=1

Use reduced concern only when majority is lost; restore only after majority is healthy (PBM guidance).


Technical troubleshooting matrix

Failure signature Root cause Diagnostic & fix
COLLSCAN / high docsExamined Missing or wrong index order Align compound index with filter + sort
WriteConcernError majority timeout Too few data-bearing nodes up Fix topology; temporary lower w with explicit risk doc
Duplicate events on retry Non-idempotent handler Upsert on natural key; store processed event IDs
Backup fails under outage PBM default majority Temporary local/w=1 per vendor docs; restore after majority
TLS handshake errors Wrong CA / SNI / cert rotation Fix tlsCAFile; rotate app certs before mongod
Transaction abort storms Multi-doc tx on hot paths Redesign embedding or outbox pattern

Best practices

  • Cap document size and array lengths; use bucket pattern for time series.
  • Use change streams with persisted resume tokens; handle invalidate on collection drops.
  • Monitor opcounters, replication lag, and index build progress.
  • Atlas: IP access lists + IAM auth; never expose 0.0.0.0/0 without explicit approval.

Limitations

  • Cross-shard transactions and global indexes add operational complexity.
  • Graph-heavy workloads may fit better elsewhere.
  • Agent suggestions cannot replace load tests on representative document sizes.

Related skills

  • @postgresql — relational alternative when joins dominate
  • @redis — cache hot Mongo reads
  • @kafka — change capture / event outbox patterns

Agent Operational Directive

MANDATORY: Always specify write/read concern implications when changing replica set topology or backup tools. Never recommend sslAllowInvalidCertificates in production. Design handlers idempotently; do not claim exactly-once without a dedupe key and proof.


Source anchors (research)