Installation¶
Requirements¶
- Python 3.14 or newer and PyMongo 4.18.1 or newer, as declared by the package.
- Caching requires MongoDB 8.0+ on a replica set or sharded cluster. Change streams are unavailable on standalone servers; the library also enforces its MongoDB version floor at startup.
- A caller-owned PyMongo client with access to the collections and their database change stream.
On standalone servers and MongoDB versions below 8.0, reads run through PyMongo without caching. The manager logs a warning when it cannot establish a database change stream; see stream health.
Install¶
Or install with pip:
For optional telemetry, install client-query-cache[otel] and follow Monitoring.
Dependency upgrades¶
Commit your application's lockfile, such as uv.lock or poetry.lock, and deploy from those selected versions. For pip-based deployments, use a pinned dependency set. See uv's locking and syncing guidance or Poetry's lockfile guidance.
PyMongo upgrades need application testing: the cache's driver integration can be sensitive to changes between releases, including patch releases. Before deploying an update, exercise cached hits and misses, cursor consumption, session bypass, startup, shutdown, and recovery in your application. A lockfile makes dependency selection reproducible; it does not prove compatibility, and passing CI covers only the behavior your checks exercise.
Local MongoDB¶
The repository’s docker-compose.yaml provides an example single-member replica set for local development. From a repository checkout, run:
The helper initializes the replica set if needed and waits until it is writable. When it exits successfully, the tutorials can connect to mongodb://localhost:27017. They write to the client_query_cache_tutorial database. This setup is for local evaluation; see deployment guidance for application deployments.
Stop the local services with:
See the official Docker Compose documentation for tool installation and usage.