🧩 mongo-ops — Async MongoDB Operations Layer for FastAPI
mongo-ops is a modular, high-performance MongoDB operations library for FastAPI microservices. It standardizes connection lifecycle, Pydantic v2 document models, and repository-style async CRUD — with added layers for caching, reference population, and multi-document transactions. It is built on top of Motor.
Doc model: this wiki is written for humans — how‑to guides, examples, and testing recipes. The authoritative API contracts live in the code (docstrings) and the machine‑readable bundle under
docs/mcp/.
🚀 Key Features
- 🧱 Unified repository pattern —
BaseRepositorywith generic CRUD - ⚡ Fully asynchronous (Motor-based)
- 🧬 Pydantic v2 data models with auto‑timestamps (
BaseDocument) - 🔒 Model registry for multi-collection startup (
ModelRegistry) - 🗄️ ID-based caching — in-memory or Redis (
cache/) - 🔗 Reference population with cycle detection (
populate/) - 🔁 Transaction and session helpers (
transactions/) - 🧪 Mock-friendly architecture — the whole repo test suite runs without MongoDB
📦 Installation
From your internal PyPI:
Bash
pip install --extra-index-url https://$PYPI_USERNAME:$PYPI_PASSWORD@pip.aetoskia.com/simple mongo-ops
With the extra batteries your workload needs:
Bash
pip install --extra-index-url https://$PYPI_USERNAME:$PYPI_PASSWORD@pip.aetoskia.com/simple "mongo-ops[redis]" # Redis cache backend
pip install --extra-index-url https://$PYPI_USERNAME:$PYPI_PASSWORD@pip.aetoskia.com/simple "mongo-ops[all]" # dev, redis, beanie, fastapi
From local source:
📁 Documentation Structure
| Section | Description |
|---|---|
| Overview | Architecture, lifecycle, and repository decision table |
| Core Components | Validated reference for the public API surface |
| Use cases | Step-by-step recipes, grouped by theme |
| · Getting Started | |
| · 01 – Basic CRUD API | FastAPI user management app |
| · 02 – Custom repository | Product catalog with business logic |
| · 06 – Multi-model | One service, many collections |
| · Data & Queries | |
| · 04 – Pagination | Filtering, sorting, page metadata |
| · 05 – Soft deletes | Recoverable delete pattern |
| · 13 – Indexes | Single, compound, and optioned indexes |
| · Caching | |
| · 07 – Caching | In-memory / Redis read cache |
| · 10 – Cache + population | Reading through cache, populating on hit |
| · 11 – Cache lifecycle | Startup/shutdown hygiene |
| · 16 – Cached repository intricacies | What's stored, JSON round-trip, typed-FK trap |
| · Population | |
| · 08 – Population | Resolve references on read |
| · 09 – Advanced population | Nested + circular references |
| · 15 – PopulatingRepository internals | Object ⇄ ObjectId write/read lifecycle, wiring |
| · 17 – Populate & depopulate examples | Worked shapes for depopulate/populate + cached round trip |
| · Advanced Usage | |
| · 03 – Transactions | Atomic order + inventory updates |
| · 12 – Transaction helper | execute_transaction |
| · 18 – Aggregation pipelines | $group, $lookup, reporting |
| · 19 – Bulk operations | update_many / delete_many / bulk_write |
| Best Practices | Layering, lifecycle, and gotchas |
| Error Handling | Library exceptions and FastAPI mapping |
| Testing | Mock Motor, engine, cache, transactions |
| · Testing example | Mock-based quickstart |
🔗 Related Resources
- Source Code: Gitea Repository
- Internal PyPI: pip.aetoskia.com/simple/mongo-ops
- Drone CI: Auto-builds and publishes tagged releases, gated on black / ruff / mypy / pytest.
© Aetoskia Internal — mongo-ops 0.1.5