mongodb.yaml

description: MongoDB best practices for security, performance, schema design, and operations
globs:
  - "**/*.js"
  - "**/*.ts"
  - "**/*mongo*"
  - "**/*repository*"
  - "**/*model*"
  - "**/*schema*"
  - "**/*.py"
  - "**/*.java"
  - "**/*.go"
  - "**/*.rb"
  - "**/mongod.conf"
rules:
  # Security Rules
  - name: enable-authentication
    description: >
      Always enable authentication in MongoDB. Use SCRAM-SHA-256 for password
      authentication. Never run MongoDB without authentication in production.
      Configure security.authorization: enabled in mongod.conf.
    severity: critical

  - name: implement-role-based-access
    description: >
      Use MongoDB's built-in roles (read, readWrite, dbAdmin) or create custom
      roles with minimal privileges. Don't grant root or dbOwner unnecessarily.
      Use different users for different application components.
    severity: high

  - name: use-field-level-encryption
    description: >
      Use Client-Side Field Level Encryption (CSFLE) for sensitive data like
      PII, health records, or financial data. Configure encryption schema and
      key management properly. Understand deterministic vs random encryption trade-offs.
    severity: high

  - name: restrict-network-exposure
    description: >
      Bind MongoDB to specific interfaces (not 0.0.0.0). Use bindIp in mongod.conf
      to restrict access. Deploy within private networks and use firewalls.
      Never expose MongoDB directly to the internet.
    severity: critical

  - name: enable-tls-encryption
    description: >
      Enable TLS/SSL for all MongoDB connections. Configure net.tls settings
      in mongod.conf. Use certificate authentication for inter-node and client
      connections. Verify certificates in production.
    severity: critical

  - name: audit-database-operations
    description: >
      Enable MongoDB auditing for compliance requirements. Configure audit
      filters to capture authentication, authorization, and data access events.
      Send audit logs to a secure, separate location.
    severity: medium

  # Performance Rules
  - name: create-appropriate-indexes
    description: >
      Create indexes for fields used in queries, sorts, and aggregations.
      Use compound indexes for multi-field queries following ESR rule
      (Equality, Sort, Range). Monitor index usage with $indexStats.
    severity: high

  - name: use-covered-queries
    description: >
      Design indexes to cover queries when possible. A covered query returns
      data directly from the index without accessing documents. Include
      all projected fields in the index for frequently executed queries.
    severity: medium

  - name: optimize-aggregation-pipelines
    description: >
      Place $match and $project stages early in aggregation pipelines to
      reduce data processed. Use $limit early when possible. Avoid $lookup
      on large collections without proper indexes. Use allowDiskUse for large sorts.
    severity: high

  - name: use-projection-to-limit-fields
    description: >
      Use projection to return only necessary fields. Large documents with
      unnecessary fields waste network bandwidth and memory. Exclude large
      fields like arrays or embedded documents when not needed.
    severity: medium

  - name: design-for-sharding
    description: >
      Choose shard keys carefully based on query patterns and data distribution.
      Avoid monotonically increasing shard keys (use hashed if needed).
      Consider shard key cardinality and query isolation for optimal performance.
    severity: high

  - name: avoid-large-in-memory-sorts
    description: >
      Create indexes to support sort operations. MongoDB has a 100MB limit
      for in-memory sorts. Use allowDiskUse for large sorts in aggregations.
      Monitor for sort stage warnings in explain output.
    severity: medium

  # Schema Design Rules
  - name: embed-vs-reference-wisely
    description: >
      Embed data for one-to-one and one-to-few relationships with frequent
      access together. Reference for one-to-many, many-to-many, or when
      subdocuments need independent access. Consider document growth patterns.
    severity: high

  - name: respect-document-size-limit
    description: >
      MongoDB has a 16MB document size limit. Design schemas to avoid
      unbounded array growth. Use bucketing pattern for large arrays.
      Consider referencing for collections that grow indefinitely.
    severity: high

  - name: use-schema-validation
    description: >
      Implement JSON Schema validation for collections. Use validationAction
      and validationLevel appropriately. Schema validation ensures data
      consistency when multiple applications access the database.
    severity: medium

  - name: use-appropriate-data-types
    description: >
      Use appropriate BSON types: Date for timestamps (not strings), Decimal128
      for financial data, ObjectId for references, NumberLong for large integers.
      Proper types enable efficient queries and reduce storage.
    severity: medium

  - name: design-for-atomicity
    description: >
      Design documents to enable atomic updates within a single document.
      Multi-document transactions are supported but have performance overhead.
      Embed data that's frequently updated together to avoid transactions.
    severity: medium

  - name: use-schema-design-patterns
    description: >
      Apply proven schema design patterns: Bucket for time-series, Computed
      for pre-aggregated data, Extended Reference for caching, Subset for
      working set optimization. Choose patterns based on access patterns.
    severity: low

  # Operations Rules
  - name: configure-replica-sets
    description: >
      Deploy MongoDB in replica sets for high availability. Use at least
      three members (or two data + one arbiter). Configure appropriate
      priority and votes for members. Test failover scenarios regularly.
    severity: critical

  - name: use-appropriate-write-concern
    description: >
      Configure write concern based on durability requirements. Use w:majority
      for critical data. Understand trade-offs between w:1 (fast, less safe)
      and w:majority (slower, durable). Set j:true for journal acknowledgment.
    severity: high

  - name: configure-read-preference
    description: >
      Use appropriate read preference for your use case. primary for strong
      consistency, secondaryPreferred for read scaling, nearest for geo-distributed
      reads. Understand stale read implications with secondary reads.
    severity: medium

  - name: implement-backup-strategy
    description: >
      Implement backup strategy using mongodump, filesystem snapshots, or
      MongoDB Atlas backups. Enable oplog for point-in-time recovery.
      Test restore procedures. Consider backup of config servers for sharded clusters.
    severity: critical

  - name: monitor-operations
    description: >
      Monitor MongoDB with serverStatus, currentOp, and profiler. Track
      opcounters, connections, memory usage, and replication lag. Use
      MongoDB Atlas, Ops Manager, or Prometheus exporters for monitoring.
    severity: medium

  - name: use-change-streams-appropriately
    description: >
      Use change streams for real-time notifications instead of polling.
      Configure resume tokens for fault tolerance. Understand change stream
      limitations with sharded clusters and pre/post images availability.
    severity: low

  - name: manage-connection-pool
    description: >
      Configure connection pool size based on concurrency needs. MongoDB
      drivers use connection pooling by default. Set maxPoolSize and
      minPoolSize appropriately. Monitor connection usage and timeouts.
    severity: medium

  - name: handle-retryable-operations
    description: >
      Enable retryable writes (retryWrites=true) for automatic retry of
      transient network errors. Use retryable reads in MongoDB 4.2+.
      Implement idempotent operations for custom retry logic.
    severity: medium