In FastAPI, when should the session dependency yield a sync Session for def endpoints and when an AsyncSession for async def endpoints?
answer
- declaration decides where code runs
- thread pool versus event loop
- blocking call on the loop thread
- awaited calls, no implicit loading
basics
~20 sPair a sync Session with def endpoints, which FastAPI runs in its thread pool, and an AsyncSession from an async generator dependency with async def endpoints. A sync Session queried inside async def blocks the event loop for every request.
solid answer
~40 sFastAPI schedules by declaration: `def` endpoints and dependencies run in the thread pool, `async def` ones on the event loop. A sync `Session` from `def get_session()` suits `def` endpoints, where each blocking query sits on a worker thread. In an `async def` endpoint the same `session.exec(...)` runs on the event loop and stalls every other request in that worker until the database answers. For `async def`, write `async def get_async_session()` that yields inside `async with AsyncSession(async_engine)` over `create_async_engine` and an async driver, and `await` every call. An `AsyncSession` cannot load from the database on plain attribute access, so an attribute expired by `commit()` cannot reload while FastAPI serializes the response; call `await session.refresh(order)` or set `expire_on_commit=False`.
go deeper
Remember the pairing: sync Session with def endpoints, AsyncSession with async def endpoints, and await every call on the async one.
Explain how FastAPI schedules def and async def endpoints and dependencies, and why a sync query inside async def stalls the whole worker.
Spot the sync-session-in-async-def bug from latency that rises across all endpoints, and know the AsyncSession traps around expired attributes and lazy loading.
Decide whether a codebase standardises on sync or async sessions, weighing simplicity and lazy loading against concurrency per worker and two pools to size.
## How FastAPI decides where code runs FastAPI looks at how each function is declared and schedules it accordingly. The same rule applies to path operations and to dependencies, including dependencies with `yield`. | Declared as | Where FastAPI runs it | |---|---| | `def` endpoint | In the thread pool, through Starlette's `run_in_threadpool` | | `async def` endpoint | Directly on the event loop | | `def` generator dependency | Entered in the thread pool; its code after `yield` runs in a worker thread too | | `async def` generator dependency | On the event loop, wrapped with `contextlib.asynccontextmanager` | Response validation follows the endpoint: for a `def` endpoint FastAPI runs it in the thread pool, for an `async def` endpoint on the event loop. ## The two pairings that work A **sync session for `def` endpoints**: ```python def get_session(): with Session(engine) as session: yield session @app.get("/orders/count") def count_orders(session: Annotated[Session, Depends(get_session)]) -> int: return len(session.exec(select(Order.id)).all()) ``` Each blocking query happens on a worker thread, so the event loop keeps serving other requests. An **async session for `async def` endpoints**, using SQLModel's `AsyncSession` and SQLAlchemy's `create_async_engine` with an async database driver: ```python async_engine = create_async_engine(DATABASE_URL) # an async driver URL async def get_async_session(): async with AsyncSession(async_engine, expire_on_commit=False) as session: yield session @app.get("/orders/count") async def count_orders(session: Annotated[AsyncSession, Depends(get_async_session)]) -> int: result = await session.exec(select(Order.id)) return len(result.all()) ``` Every database call is awaited, so a request waiting on the database yields the event loop to the others. ## The mismatch that stalls a worker The common bug is a sync `SessionDep` inside an `async def` endpoint: 1. FastAPI enters the `def` dependency in the thread pool, which looks harmless. 2. The endpoint is `async def`, so FastAPI calls it on the event loop. 3. `session.exec(...)` blocks that thread until the database answers. 4. While it blocks, no other request in that worker process makes progress: health checks, other endpoints and streaming responses all wait. It passes tests and light traffic, then latency climbs across every endpoint once queries slow down. The fix is to make the endpoint `def`, or to switch that path to an `AsyncSession`. The mirror mistake is an `AsyncSession` handed to a `def` endpoint, which cannot `await` anything at all. ## What changes with an AsyncSession - **Every database call is awaited**: `await session.exec(...)`, `await session.commit()`, `await session.refresh(order)`. - **No implicit I/O**: an attribute that needs a database round trip cannot load on plain attribute access. Relationships are therefore loaded eagerly in the query or awaited explicitly, not lazily on access. - **Expired attributes after commit**: by default a commit expires loaded attributes. When FastAPI then serializes the returned object for the response, reading them needs I/O that cannot happen implicitly, and serialization fails. Either `await session.refresh(order)` before returning or create sessions with `expire_on_commit=False`. - **No thread-pool ceiling**: `async def` endpoints do not take thread tokens, so the engine's pool and its timeout become the only limit on concurrent database work. ## Signs of the mismatch in a running service A sync session in an `async def` endpoint rarely fails a test, because tests send one request at a time against a fast local database. It shows up in production in recognisable ways: - Latency rises on **every** endpoint of the worker at once, including ones that never touch the database, whenever one slow query runs. - Health checks time out during slow queries, so the container platform restarts healthy workers. - Throughput per worker stops growing with concurrency, because the event loop is busy waiting instead of switching between requests. - Profiling shows the event loop thread spending its time inside the database driver's blocking calls. Changing the endpoint to `def` usually removes all four symptoms immediately, which is also the quickest way to confirm the diagnosis. ## Choosing for a codebase - Choose by the endpoint's declaration: one session type per path, never a sync session in `async def`. - Sync sessions with `def` endpoints are simpler and keep lazy loading; they are capped by the thread pool. - Async sessions suit endpoints that already `await` other I/O, such as calls to other services, and want high concurrency per worker. - Mixing both in one app is fine when each route uses the dependency that matches its declaration, but it means two engines and two pools to size.
- Is a def get_session dependency safe in an async def endpoint if every query is fast?No. FastAPI enters the dependency in the thread pool, but the queries the endpoint body makes run on the event loop, so each one blocks every other request in that worker while it runs. Fast queries hide it in testing; under load or a slow database it becomes latency on every endpoint. Declare the endpoint `def`, or give that route an `AsyncSession`.
- Why do async session dependencies often set expire_on_commit=False?After `commit()` SQLAlchemy expires the loaded attributes so the next access reloads them. Under an `AsyncSession` that reload cannot happen on plain attribute access, and FastAPI reads those attributes when it serializes the returned object. Setting `expire_on_commit=False` keeps the committed values in memory; the alternative is an explicit `await session.refresh(order)` before returning.
- Declaring the endpoint async def makes a sync Session's queries non-blocking.
- FastAPI runs every endpoint in the thread pool, so blocking queries are always safe.
- An AsyncSession works from a def endpoint if its methods are called without await.
- Lazy-loaded relationships behave the same under an AsyncSession as under a Session.