Client-side query caching for PyMongo

client-query-cache uses MongoDB change streams to asynchronously invalidate cached query results. It supports synchronous and asyncio applications without requiring a separate cache server.

%%{init: {"flowchart": {"diagramPadding": 75}}}%%
flowchart LR
    App["Python<br/>application"] -->|"Reads"| Cache["Client-side<br/>caching"]
    Cache -->|"Miss / bypass"| DB[("MongoDB")]
    DB -.->|"Change streams<br/>Async invalidation"| Cache

Cache hits are served from client-side memory, reducing read latency and database load in read-heavy applications.

The library is tested against real MongoDB replica sets, including concurrency stress tests, and automated checks guard its performance and memory use against regressions.

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; see consistency.

Eligible cache misses read from the primary with majority read concern, even when the collection leaves read concern unspecified, so only majority-committed results enter the cache. Uncached PyMongo reads use the deployment's default read concern, normally local. The two usually perform alike, but while replication lags or data-bearing members are unavailable, a miss can return older data or fail where an uncached read would not. Majority admission does not make cache hits current: invalidation remains asynchronous. See bypass conditions.

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_manager,
):
    collection = client["client_query_cache_tutorial"]["items"]
    cached_collection = cache_manager.get_cached_collection(collection)
    collection.replace_one(
        {"_id": "example"}, {"_id": "example", "value": 42}, upsert=True
    )
    cached_collection.find_one({"_id": "example"})  # Reads from MongoDB.
    cached_collection.find_one({"_id": "example"})  # Repeated reads can use the cache.

Shared application workers

For several trusted workers on one Linux x86-64 host, SharedCacheServer and sync/async SharedCacheManager share cached find_one() reads by _id and database change streams. Start the server in the application parent and attach each worker's own PyMongo client. Other reads use PyMongo. See the shared-cache deployment guide for the supported platform and lifecycle.

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.