Coherent client-side caching for PyMongo

client-query-cache uses MongoDB change streams to keep cached reads coherent. It supports synchronous and asyncio applications without requiring a separate cache server.

Built for production: Designed for high-traffic, read-heavy applications, with cache hits served from memory to reduce latency and database load. Quality is backed by a 100% test-coverage requirement, real MongoDB integration and concurrency stress tests, and automated performance and memory regression checks.

Results vary by workload and deployment. Measurements and methodology.

Caching requires MongoDB 8.0+ on a replica set or sharded cluster. Reads on standalone servers and older MongoDB versions run through PyMongo without caching.

Invalidation is asynchronous: a cached read can return a preceding value until the write's change-stream event is processed. Use PyMongo directly when a read must immediately observe a preceding write.

Quick start

uv add client-query-cache

Or use pip install client-query-cache.

from pymongo import MongoClient

from client_query_cache import CacheManager

with (
    MongoClient("mongodb://localhost:27017") as client,
    CacheManager(client) as cache,
):
    users = cache.get_cached_collection(client["my_database"]["users"])
    users.find_one({"_id": "alice"})  # Reads from MongoDB.
    users.find_one({"_id": "alice"})  # Repeated reads can use the cache.

References

Getting started · Benchmarks · Examples

MongoDB is a registered trademark of MongoDB, Inc. This project is independent and is not affiliated with or endorsed by MongoDB, Inc.