0Pricing
FastAPI Backend Development Bootcamp · Lektion

Asynchroner MongoDB-Zugriff mit Motor

Verbinden Sie FastAPI über den asynchronen Motor-Treiber mit MongoDB und verwalten Sie Verbindungslebenszyklen im App-Lifespan.

Asynchroner MongoDB-Zugriff mit Motor ist eine kostenlose FastAPI Backend Development Bootcamp-Lektion auf CoddyKit. Dies ist Lektion 1 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des FastAPI Backend Development Bootcamp-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der FastAPI Backend Development Bootcamp-Kurs umfasst insgesamt 4 Lektionen.

Teile dieser Lektion wurden noch nicht übersetzt und werden auf Englisch angezeigt.

Why Motor for Async MongoDB

FastAPI is an async framework. If you talk to MongoDB with a blocking driver like pymongo, every database call freezes the event loop and kills concurrency.

Motor is MongoDB's official async driver. It wraps PyMongo and exposes coroutine-based methods you can await, so the event loop stays free to handle other requests while a query is in flight.

  • motor.motor_asyncio.AsyncIOMotorClient — the async client.
  • Every I/O call (find_one, insert_one, ...) returns an awaitable.
  • Higher-level ODMs like Beanie are built on top of Motor.

Installing the Driver

Install Motor and its peer dependency. Motor pulls in a compatible PyMongo automatically.

  • motor — async driver.
  • fastapi and uvicorn — the web layer.

For Beanie integration later you would also add beanie, but Motor alone is enough to read and write documents directly.

pip install motor fastapi uvicorn
# motor brings in a compatible pymongo wheel
# verify the install
python -c "import motor; print(motor.version)"

Creating an Async Client

You create a single AsyncIOMotorClient for the whole application. The client manages an internal connection pool, so you should never create a new client per request.

Indexing into the client gives you a database, and indexing into that gives you a collection. None of this opens a socket yet — connections are established lazily on the first real operation.

from motor.motor_asyncio import AsyncIOMotorClient

client = AsyncIOMotorClient("mongodb://localhost:27017")
database = client["shop"]
products = database["products"]

# Equivalent attribute-style access
# database = client.shop
# products = database.products

Awaiting Your First Query

Because every Motor I/O method is a coroutine, you must await it inside an async function. Forgetting await returns an unresolved coroutine object, not your data.

insert_one returns an InsertOneResult whose inserted_id is the generated ObjectId. find_one returns the matching document as a plain dict, or None.

import asyncio
from motor.motor_asyncio import AsyncIOMotorClient

async def main():
    client = AsyncIOMotorClient("mongodb://localhost:27017")
    products = client["shop"]["products"]

    result = await products.insert_one({"name": "Keyboard", "price": 49})
    print("inserted id:", result.inserted_id)

    doc = await products.find_one({"name": "Keyboard"})
    print(doc)

asyncio.run(main())

The Connection Lifecycle Problem

Where should the client live? Options that look tempting but are wrong:

  • A new client inside each route — exhausts connections and is slow.
  • A module-level client created at import time — connects before the app is ready and is hard to close cleanly.

The right place is the app's lifespan: open the client when the server starts, store it, and close it when the server shuts down. This guarantees one pooled client per process and a clean teardown.

The Lifespan Context Manager

Modern FastAPI uses an async context manager passed as lifespan. Code before yield runs on startup; code after yield runs on shutdown.

Store shared resources on app.state so any route can reach them. Calling client.close() on shutdown returns pooled sockets to the OS gracefully.

from contextlib import asynccontextmanager
from fastapi import FastAPI
from motor.motor_asyncio import AsyncIOMotorClient

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.mongo = AsyncIOMotorClient("mongodb://localhost:27017")
    app.state.db = app.state.mongo["shop"]
    yield
    app.state.mongo.close()

app = FastAPI(lifespan=lifespan)

Verifying the Connection on Startup

The client connects lazily, so a wrong host won't fail until the first query. To fail fast at boot, send a lightweight ping command during startup.

If the ping raises, the server crashes immediately with a clear error instead of silently serving 500s later.

from contextlib import asynccontextmanager
from fastapi import FastAPI
from motor.motor_asyncio import AsyncIOMotorClient

@asynccontextmanager
async def lifespan(app: FastAPI):
    client = AsyncIOMotorClient("mongodb://localhost:27017")
    await client.admin.command("ping")  # raises if unreachable
    app.state.db = client["shop"]
    app.state.mongo = client
    yield
    client.close()

app = FastAPI(lifespan=lifespan)

Injecting the Database into Routes

Reaching into request.app.state directly works but couples routes to global state. A cleaner pattern is a small dependency that returns the database handle.

This keeps routes testable — in tests you can override the dependency to point at a throwaway database.

from fastapi import Depends, Request
from motor.motor_asyncio import AsyncIOMotorDatabase

def get_db(request: Request) -> AsyncIOMotorDatabase:
    return request.app.state.db

@app.get("/products/{name}")
async def get_product(name: str, db: AsyncIOMotorDatabase = Depends(get_db)):
    doc = await db["products"].find_one({"name": name})
    return doc or {"error": "not found"}

Serializing the ObjectId

MongoDB documents carry an _id field of type ObjectId, which is not JSON serializable. Returning a raw document from a route triggers a serialization error.

Convert _id to a string before returning, or map it into a Pydantic model. A simple helper keeps your routes clean.

def serialize(doc: dict) -> dict:
    if doc and "_id" in doc:
        doc["id"] = str(doc["_id"])
        del doc["_id"]
    return doc

# Usage inside a route:
# raw = await db["products"].find_one({"name": name})
# return serialize(raw)

print(serialize({"_id": "507f1f77bcf86cd799439011", "name": "Mouse"}))

Iterating Cursors Asynchronously

find() returns an async cursor, not a list. You consume it with async for, or materialize it with to_list().

  • await cursor.to_list(length=100) — load up to 100 docs at once.
  • async for doc in cursor: — stream documents one at a time, ideal for large result sets.
from fastapi import Depends
from motor.motor_asyncio import AsyncIOMotorDatabase

@app.get("/products")
async def list_products(db: AsyncIOMotorDatabase = Depends(get_db)):
    cursor = db["products"].find({"price": {"$lt": 100}})
    return await cursor.to_list(length=50)

# Streaming alternative:
# async for doc in cursor:
#     process(doc)

Configuring the Pool and Timeouts

The client constructor accepts tuning options. Read them from environment variables so the same code works across dev and production.

  • maxPoolSize — cap on concurrent connections.
  • serverSelectionTimeoutMS — how long to wait before declaring the server unreachable.

Loading the URI from the environment also keeps credentials out of source control.

import os
from motor.motor_asyncio import AsyncIOMotorClient

def make_client() -> AsyncIOMotorClient:
    uri = os.environ.get("MONGODB_URI", "mongodb://localhost:27017")
    return AsyncIOMotorClient(
        uri,
        maxPoolSize=20,
        serverSelectionTimeoutMS=5000,
    )

Quick Check

Where should the AsyncIOMotorClient be created and destroyed in a FastAPI app?

Recap

You connected FastAPI to MongoDB with the async Motor driver:

  • Motor exposes awaitable methods so MongoDB I/O never blocks the event loop.
  • Create one AsyncIOMotorClient per process — it owns a connection pool.
  • Open and close the client in the lifespan context manager, and ping on startup to fail fast.
  • Expose the database through a Depends dependency for clean, testable routes.
  • Convert _id (an ObjectId) to a string before returning JSON.
  • Consume find() cursors with to_list() or async for, and tune maxPoolSize and timeouts from environment variables.

This Motor foundation is exactly what Beanie builds on next.

Häufig gestellte Fragen

Ist die Lektion „Asynchroner MongoDB-Zugriff mit Motor“ kostenlos?

Ja — der vollständige Text von „Asynchroner MongoDB-Zugriff mit Motor“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des FastAPI Backend Development Bootcamp-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der FastAPI Backend Development Bootcamp-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Asynchroner MongoDB-Zugriff mit Motor“?

Verbinden Sie FastAPI über den asynchronen Motor-Treiber mit MongoDB und verwalten Sie Verbindungslebenszyklen im App-Lifespan. Du übst FastAPI Backend Development Bootcamp mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um FastAPI Backend Development Bootcamp zu starten?

Keine Vorkenntnisse erforderlich. FastAPI Backend Development Bootcamp auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 1 von 4.

Wie lange dauert die Lektion „Asynchroner MongoDB-Zugriff mit Motor“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser FastAPI Backend Development Bootcamp-Lektion Code schreiben und ausführen?

Ja. Jede FastAPI Backend Development Bootcamp-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

  1. Asynchroner MongoDB-Zugriff mit Motor
  2. Dokumentmodellierung mit Beanie ODM
  3. Aggregationspipelines und komplexe Queries
  4. Schemaentwicklung und Dokumentmigrationen
← Zurück zu FastAPI Backend Development Bootcamp