On this page
Set of computers showing infrastructure for databases. Image by Suresh anchan from Pixabay.

Caching Mongoose queries in a native MongoDB collection

If you’re building a Node.js application with Mongoose, you’ve probably felt the pain of database performance at scale. The go-to solution? Add Redis. Set up a caching layer, wire it into your queries, and hope the invalidation logic doesn’t become a maintenance nightmare.

But what if we told you there’s a simpler way – one that uses the database you already have, requires zero additional infrastructure, and handles cache invalidation automatically?

Meet @sitelintpackages/mongoose-cache: a MongoDB-based caching solution for Mongoose queries with TTL and automatic invalidation support.

The problem with traditional caching

Caching database queries is one of the most effective ways to improve application performance. But implementing it properly is deceptively complex:

  • Cache invalidation – the hardest problem in computer science – requires tracking which queries are affected by every write operation.
  • Distributed coordination – when you scale horizontally across multiple PM2 instances or containers, caches need to stay synchronized.
  • Infrastructure overhead – Redis means another service to deploy, monitor, secure, and pay for.
  • Stale data risks – partial or incorrect invalidation leads to users seeing outdated information.

Most existing Mongoose caching packages (like mongoose-cache, ts-cache-mongoose, or recachegoose) rely on in-memory LRU caches or Redis. These approaches work, but they come with tradeoffs.

A aifferent approach with MongoDB as cache storage

@sitelintpackages/mongoose-cache takes a fundamentally different approach. Instead of adding a separate caching layer, it stores serialized query results directly in MongoDB under a dedicated _cache_entries collection.

Why MongoDB?

The solution aims to:

  • Zero infrastructure – no additional service to deploy, monitor, or secure.
  • Atomic consistency – cache writes and invalidations share the same connection pool as application data, reducing race-condition surface.
  • Multi-instance safe – PM2, cluster, or horizontally scaled API instances all read/write the same cache collection without coordination.
  • Built-in TTL – MongoDB’s native TTL index on expiresAt provides automatic document expiry.

The cache bypasses Mongoose models entirely and uses the native MongoDB driver (db.collection()) to avoid recursive caching – cached reads never pass through the patched Mongoose layer.

Key features

1. Query caching

Simply opt-in with .set('useCache', true):

Cache usage example
const users = await User.find({ active: true })
  .set('useCache', true)
  .set('cacheTTL', 60000) // optional, defaults to 7 days
  .exec();

Works with find, findOne, findById, and aggregation pipelines.

Recommendation: always wrap await expressions in a try...catch block. Any rejected promise will throw an exception, and failing to handle it can result in unhandled promise rejections, application instability, or unexpected process termination. Explicit error handling makes failures predictable and easier to debug.

2. Automatic invalidation

Write operations automatically invalidate affected cache entries – no manual cleanup required:

  • save(), updateOne(), deleteMany()
  • insertMany(), bulkWrite()
  • Aggregation stages like $merge and $out

The invalidation strategy is deliberately coarse-grained: any write to a collection deletes all cache entries for that collection. This avoids the complexity of partial invalidation while still being highly effective.

3. Cross-collection invalidation

When a query uses .populate(), the plugin introspects Mongoose’s internal populate options to determine which collections are referenced. A write to any populated collection also invalidates the parent query’s cache entry.

4. Size limit and periodic sweep

Configurable maxCacheSizeBytes prevents unbounded growth. When the limit is hit, new writes are skipped (the query still executes and returns data). A background sweep runs periodically to clean expired entries.

5. Connection-pool resilience

All cache operations gracefully handle MongoPoolClearedError (common during replica-set elections or network issues). Reads become cache misses, writes are skipped, invalidations are deferred – the application continues serving uncached data until the pool recovers.

6. Multi-database support

Register connections to different databases; each gets its own _cache_entries collection. Cache keys include the database name to avoid collisions.


How it works: architecture

The plugin uses a monkey-patching strategy – it patches Mongoose prototypes globally once, on first schema registration:

Architecture
TargetWhat it patches
Query.prototype.exec Intercepts all queries. Destructive ops auto-invalidate. Read ops check cache before executing.
Model.aggregate Wraps aggregates to check/update cache at .exec() time. Detects $merge/$out write stages.
Model.insertManyInvalidates the collection after bulk inserts.
Model.bulkWriteInvalidates the collection after bulk writes.
schema.post('save')Per-schema hook that invalidates on every save().

The patching is guarded by module-level booleans so it never happens twice – even if cachePlugin is called on multiple schemas.

┌──────────────────────────────────────────────────────┐
│                    Application                       │
│                                                      │
│  Model.find().set('useCache',true).exec()            │
│                                                      │
│  ▼                                                   │
│  Query.prototype.exec (patched by cachePlugin)       │
│                                                      │
│  ├── cache HIT? ──── return cached result            │
│  │                                                   │
│  ├── cache MISS ─── originalQuery.exec()             │
│  │                     │                             │
│  │                     ▼                             │
│  │              MongoDB (source collection)          │
│  │                     │                             │
│  │                     ▼                             │
│  └── CacheDb.writeCache(key, entry)                  │
│                                                      │
│  ▼                                                   │
│  MongoDB._cache_entries (native driver)              │
└──────────────────────────────────────────────────────┘
Cache lookup flow with @sitelintpackages/mongoose-cache

Scalability benefits

  • Bypasses Mongoose – cache reads use native findOne against _cache_entries, avoiding the overhead of Mongoose hydration, schema validation, middleware, and getters. A cache hit returns raw JSON in a single round-trip.
  • Index-backed lookups – the _cache_entries collection has indexes on meta.collection and meta.populatedCollections so invalidations are fast regardless of cache size.
  • No cross-instance coordination – since the cache state lives in MongoDB, adding more app instances requires no additional synchronization.

Quick start

Quick start example
import mongoose from 'mongoose';
import { CacheDb, cachePlugin } from '@sitelintpackages/mongoose-cache';

// 1. Apply the plugin to your schemas
const userSchema = new mongoose.Schema({ name: String, email: String });
userSchema.plugin(cachePlugin);
const User = mongoose.model('User', userSchema);

try {
  // 2. Pass your Mongoose connection
  const connection = await mongoose.connect('mongodb://localhost:27017/myapp');
  CacheDb.setConnection(connection);

  // Or if you already have an active connection:
  // CacheDb.setConnection(mongoose.connection);

  await CacheDb.initializeCacheDB();

  // Optional: configure size limit and periodic sweep
  CacheDb.configure({ maxCacheSizeBytes: 500 * 1024 * 1024 }); // 500 MB
  CacheDb.initializePeriodTasks({
    sweepIntervalMs: 75 * 60 * 1000,
  }); // every 75 min
} catch (error) {
  console.error('Failed to initialize MongoDB cache:', error);
}

try {
  // 3. Use .set('useCache', true) on read queries
  const users = await User.find({ active: true })
    .set('useCache', true)
    .set('cacheTTL', 60000)
    .exec();

  console.log(users);
} catch (error) {
  console.error('Failed to fetch users:', error);
}

try {
  // 4. Write operations auto-invalidate
  await User.updateOne({ _id: '...' }, { name: 'Bob' });

  // The cache for the "users" collection is cleared automatically
} catch (error) {
  console.error('Failed to update user:', error);
}

Comparison: Redis vs. MongoDB-native caching

Redis vs. MongoDB-native caching
AspectRedis-based caching@sitelintpackages/mongoose-cache
InfrastructureAdditional service to deploy and monitorNo extra service needed
ConsistencyPotential race conditions between cache and DBAtomic – same connection pool
Horizontal scalingRequires shared Redis instance or clusterNo coordination needed – cache lives in MongoDB
InvalidationUsually manual or custom logicAutomatic on all write operations
Populate supportOften unsupported or limitedAutomatic cross-collection invalidation
ResilienceNetwork dependency adds failure pointGracefully handles connection issues
CostAdditional infrastructure costIncluded in existing MongoDB deployment

When to use this package

This package is particularly well-suited for:

  • Applications already using MongoDB – you get caching without adding complexity.
  • Microservices with shared databases – cache consistency is automatic.
  • PM2/cluster deployments – no need for Redis coordination.
  • Teams that want “it just works” caching – the plugin handles invalidation automatically.
  • Applications where Redis isn’t already in the stack – reduce infrastructure footprint.

Consider alternatives if:

  • You need sub-millisecond cache latency (Redis in-memory is faster than MongoDB).
  • You’re already heavily invested in Redis for other purposes.
  • Your MongoDB deployment is already under heavy load.

Best practices

1. Start with high-impact queries

Apply useCache: true to queries that are:

  • Frequently executed.
  • Expensive to compute (complex aggregations, large result sets).
  • Read-heavy with infrequent writes.

2. Set appropriate TTLs

The default TTL is 7 days, but adjust based on data volatility:

  • Frequently changing data leads to shorter TTL (e.g., 5 minutes).
  • Static reference data leads to longer TTL (e.g., 24 hours).

3. Monitor cache size

Configure maxCacheSizeBytes based on your available storage and cache hit ratio. Start with a conservative limit (e.g., 500 MB) and adjust based on monitoring.

4. Understand the coarse-grained invalidation

The plugin invalidates entire collections on any write – this is simple and correct, but means high-write collections won’t benefit much from caching. Use it where reads significantly outweigh writes.

5. Test cache behavior under load

The package handles connection-pool resilience gracefully, but test how your application behaves when the cache is unavailable (it should fall back to uncached queries).

Comparison with other solutions

Feature@sitelintpackages/mongoose-cachets-cache-mongooserecachegoose / mongoose-cache
StorageMongoDB collectionMemory or RedisRedis or memory
Infra requiredNoneRedis optionalRedis required
Auto-invalidationYes (query-aware)No (manual)Partial
Multi-instance safeYesOnly with RedisYes (Redis)
Aggregation cachingYesYesLimited
Cross-collection invalidationYesNoNo
Staleness riskLowMediumMedium
MaturityNewerMatureMature but older

Final thoughts

@sitelintpackages/mongoose-cache challenges the assumption that effective caching requires Redis. By leveraging MongoDB’s native capabilities and a thoughtful invalidation strategy, it delivers a caching layer that’s:

  • Dead simple to implement – just apply the plugin and opt-in to caching.
  • Automatically correct – invalidation handles writes, updates, and populated collections.
  • Infrastructure-light – no new services to deploy or manage.
  • Production-ready – handles connection failures, size limits, and multi-instance deployments.

For many Node.js/Mongoose applications, this MongoDB-native approach is not just simpler – it’s better.

Have you tried MongoDB-native caching for your Mongoose queries? We’d love to hear about your experience in the comments.

Related posts

Search in sitelint.com

Is your site slow?

Discover performance bottlenecks to provide a better customer experience and meet your company’s revenue targets.