Skip to content

🧩 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 — BaseRepository with 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:

Bash
pip install -e .

📁 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
· 01 – Basic CRUD API FastAPI user management app
· 02 – Custom repository Product catalog with business logic
· 03 – Transactions Atomic order + inventory updates
· 04 – Pagination Filtering, sorting, page metadata
· 05 – Soft deletes Recoverable delete pattern
· 06 – Multi-model One service, many collections
· 07 – Caching In-memory / Redis read cache
· 08 – Population Resolve references on read
· 09 – Advanced population Nested + circular references
· 10 – Cache + population Reading through cache, populating on hit
· 11 – Cache lifecycle Startup/shutdown hygiene
· 12 – Transaction helper execute_transaction
· 13 – Indexes Single, compound, and optioned indexes
· 14 – Testing guide Mock Motor, engine, cache, transactions
· 15 – PopulatingRepository internals Object ⇄ ObjectId write/read lifecycle, wiring
· 16 – Cached repository intricacies What's stored, JSON round-trip, typed-FK trap
Best Practices Layering, lifecycle, and gotchas
Common Patterns Service layer, aggregation, bulk ops
Error Handling Library exceptions and FastAPI mapping
Testing Example Mock-based quickstart

© Aetoskia Internal — mongo-ops 0.1.5