
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
expiresAtprovides 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):
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.
2. Automatic invalidation
Write operations automatically invalidate affected cache entries – no manual cleanup required:
save(),updateOne(),deleteMany()insertMany(),bulkWrite()- Aggregation stages like
$mergeand$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:
| Target | What 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.insertMany | Invalidates the collection after bulk inserts. |
Model.bulkWrite | Invalidates 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) │
└──────────────────────────────────────────────────────┘@sitelintpackages/mongoose-cacheScalability benefits
- Bypasses Mongoose – cache reads use native
findOneagainst_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_entriescollection has indexes onmeta.collectionandmeta.populatedCollectionsso 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
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
| Aspect | Redis-based caching | @sitelintpackages/mongoose-cache |
|---|---|---|
| Infrastructure | Additional service to deploy and monitor | No extra service needed |
| Consistency | Potential race conditions between cache and DB | Atomic – same connection pool |
| Horizontal scaling | Requires shared Redis instance or cluster | No coordination needed – cache lives in MongoDB |
| Invalidation | Usually manual or custom logic | Automatic on all write operations |
| Populate support | Often unsupported or limited | Automatic cross-collection invalidation |
| Resilience | Network dependency adds failure point | Gracefully handles connection issues |
| Cost | Additional infrastructure cost | Included 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-cache | ts-cache-mongoose | recachegoose / mongoose-cache |
|---|---|---|---|
| Storage | MongoDB collection | Memory or Redis | Redis or memory |
| Infra required | None | Redis optional | Redis required |
| Auto-invalidation | Yes (query-aware) | No (manual) | Partial |
| Multi-instance safe | Yes | Only with Redis | Yes (Redis) |
| Aggregation caching | Yes | Yes | Limited |
| Cross-collection invalidation | Yes | No | No |
| Staleness risk | Low | Medium | Medium |
| Maturity | Newer | Mature | Mature 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.