Skip to content

Library Overview

mongo-ops gives FastAPI/microservice teams a small, opinionated toolkit for talking to MongoDB asynchronously. This page builds the mental model: what the layers are, in what order they must be wired up, and which repository to reach for.

🏗️ Architecture

Text Only
┌───────────────────────────────────────────────────────────┐
│  Application (FastAPI)                                    │
│  ┌─────────────┬───────────────┬───────────────┬─────────┐ │
│  │ CachedBase  │ Populating    │ BaseRepository│  Raw    │ │
│  │ Repository  │ Repository    │ (CRUDMixin)   │ Motor   │ │
│  └──────┬──────┴───────┬───────┴───────┬───────┴─────────┘ │
│         │              │               │                   │
│  ┌──────┴──────┐  ┌────┴──────┐  ┌─────┴─────────────────┐ │
│  │ Cache backend│  │ Population│  │ TransactionManager    │ │
│  │ memory/redis │  │ Engine    │  │ (session helpers)     │ │
│  └──────┬──────┘  └────┬──────┘  └─────────┬─────────────┘ │
│  ┌──────┴──────────────────────────────────┴─────────────┐ │
│  │ ModelRegistry  (models, indexes, cache lifecycle)      │ │
│  └──────┬─────────────────────────────────────────────────┘ │
│  ┌──────┴─────────────────────────────────────────────────┐ │
│  │ MongoConnectionManager  (Motor client + database)      │ │
│  └──────────────────────────┬──────────────────────────────┘ │
└─────────────────────────────┼────────────────────────────────┘
                              ▼
                        MongoDB (Motor / PyMongo)

The layers build on each other:

  1. Connection — MongoConnectionManager owns the Motor client and active database.
  2. Models — BaseDocument (Pydantic v2) gives every document id (aliased _id) plus created_at / updated_at.
  3. CRUD — CRUDMixin / BaseRepository implement generic async CRUD against a collection.
  4. Startup — ModelRegistry centralizes model + index registration and cache lifecycle for multi-collection services.
  5. Advanced layers — caching and population compose around a repository:
  6. CachedBaseRepository wraps BaseRepository with a CacheBackend.
  7. PopulatingRepository wraps BaseRepository with a PopulationEngine.
  8. Transactions — TransactionManager runs a list of async operations atomically on a session.

🔄 Lifecycle Rules

mongo-ops has a strict startup order. Violating it raises fast, loud exceptions:

Step Call Why
1 await MongoConnectionManager.connect(uri, db_name) Without a connection, get_database()/get_client() raise RuntimeError("Database not connected...").
2 await ModelRegistry.initialize_all() Create registered indexes (idempotent via create_index).
3 await ModelRegistry.set_cache_backend(...) then await ModelRegistry.initialize_cache() Must happen after connection, before any cache-backed operation. Raises RuntimeError("No cache backend registered...") if skipped.
4 Use repositories Constructed repos resolve the collection from the live database.
5 await ModelRegistry.shutdown_cache() + await MongoConnectionManager.disconnect() On shutdown (in-memory TTL task cancelled; Redis pub/sub closed).

The canonical wiring is the FastAPI lifespan context manager (see use case 01).

🧭 Which Repository Should You Use?

Repository Use when Adds
BaseRepository[T] Plain CRUD — the default nothing extra
CachedBaseRepository[T] Read‑heavy, low‑write fields (lookups by _id) cache‑first get_by_id, cache on create, invalidate on update/delete, warm_cache
PopulatingRepository[T] You return related docs (FK references) denormalized _populate on read, _depopulate on write, FK‑guarded patch
CRUDMixin Reusing CRUD inside an existing class raw CRUD against a collection you already have

There is no built‑in CachedPopulatingRepository. Use case 10 shows how to compose caching + population in a small subclass.