mongodb
Design MongoDB documents and indexes, build aggregation pipelines, and investigate query plans or transaction behavior.
SKILL.mdskills/mongodb/SKILL.md
GitHubMongoDB 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
- Connection safety: Full SRV URI with
replicaSet,authSource,tls=true, and cert options for self-hosted; capmaxPoolSize; setserverSelectionTimeoutMSandconnectTimeoutMS. - Write concern: Default global
majorityis common; on P-S-A (primary + secondary + arbiter),w: majoritycan fail when the only data-bearing secondary is down—size replica sets for real redundancy or document degraded modes explicitly. - Indexes: Equality fields first in compound index, then sort, then range; use partial and TTL indexes intentionally; avoid unbounded array growth.
- Migrations: Prefer additive schema +
$jsonSchemavalidation; online index builds still load the cluster—build during low traffic withbackgroundequivalent (modern builds use index build coordination—check server version docs). - 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.
- Auth: Database users with least privilege;
readPreferencesecondary for analytics only when stale reads are acceptable. - Exactly-once myth: Retryable writes prevent duplicate keys on idempotent ops but do not make downstream handlers exactly-once—use idempotent
updateOnefilters 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
invalidateon collection drops. - Monitor
opcounters, replication lag, and index build progress. - Atlas: IP access lists + IAM auth; never expose
0.0.0.0/0without 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
sslAllowInvalidCertificatesin production. Design handlers idempotently; do not claim exactly-once without a dedupe key and proof.