How does FastAPI async SQLAlchemy work under the hood?

FastAPI with async SQLAlchemy has four layers. FastAPI runs your async def endpoint as a coroutine on a single event loop. A dependency hands that endpoint an AsyncSession. The AsyncSession and AsyncEngine are thin wrappers around SQLAlchemy's ordinary synchronous Session and Engine. Underneath, an async DBAPI driver such as asyncpg does the network IO.

SQLAlchemy did not rewrite its ORM for asyncio. Instead, it runs the existing sync code inside a greenlet. When that code reaches a point where it needs IO, such as sending a query or fetching rows, the greenlet switches control to the event loop. The loop awaits the asyncpg call and then resumes the greenlet with the result. Because of this design, the full ORM is available without duplicating it.

A typical query follows this path:

  1. The endpoint awaits session.execute(...).
  2. The AsyncSession starts the sync Session call inside a greenlet.
  3. The sync code checks out a connection from SQLAlchemy's pool, which holds asyncpg connections.
  4. At the IO boundary, the greenlet yields to the event loop, which awaits asyncpg and resumes the greenlet when Postgres responds.

The bridge works only when IO starts from inside that greenlet context. Accessing an unloaded relationship attribute triggers a lazy load, which is implicit IO from plain synchronous attribute access. Nothing awaited it, so no greenlet is available to yield, and SQLAlchemy raises MissingGreenlet.

That boundary is where most production incidents come from. The usual causes are code that blocks the loop, IO that happens outside the bridge, and sessions that no one closes. In most cases, the async machinery itself is not the problem.

+----------------------------------------------------------------+
| Event loop (one thread)                                        |
|  +-------------------------+     +--------------------------+  |
|  | async def endpoint      |<----| Depends: get_session()   |  |
|  | await session.execute() |     | yields AsyncSession      |  |
|  +------------+------------+     +--------------------------+  |
|               | await                                          |
|               v                                                |
|  +-------------------------+                                   |
|  | AsyncSession            |                                   |
|  | wraps sync Session      |                                   |
|  +------------+------------+                                   |
|               | runs sync code in a greenlet                   |
|               v                                                |
|  +-------------------------+  IO: switch  +-----------------+  |
|  | greenlet: sync Session  |------------->| loop awaits     |  |
|  | checks out asyncpg conn |<-------------| asyncpg I/O     |  |
|  +-------------------------+  resume      +--------+--------+  |
+----------------------------------------------------|-----------+
                                                     v
                                             +----------------+
                                             | PostgreSQL     |
                                             +----------------+

Failure: obj.relationship (plain attribute access, nothing awaited)
  --> lazy load needs IO --> no greenlet to switch --> MissingGreenlet

An awaited query runs from the endpoint through the injected AsyncSession into a greenlet that runs the sync Session and switches to the event loop for asyncpg I/O, while an unawaited lazy load has no greenlet to switch from and raises MissingGreenlet.

What blocks the event loop in an async FastAPI endpoint, and how do you detect it?

An event loop runs one callback at a time. When a coroutine calls something that does not yield, the loop cannot switch to anything else until that call returns. Every request on that worker waits, including health checks and requests that never touch the database. A 200 ms blocking query does not slow one request by 200 ms. It adds up to 200 ms to every request in flight on that process.

Common blocking calls

  • Sync database drivers. Examples are psycopg2, or a sync Session used inside async def.
  • Sync HTTP clients. requests is the usual one, often hidden inside an SDK.
  • time.sleep(), typically in retry or backoff code.
  • CPU-heavy work. This includes serializing large result sets, hashing passwords and parsing large JSON payloads.
  • File IO. Plain open() and read() on local or network filesystems block.

A typical fix: a handler calls requests.get(url) inside async def. Replace it with a shared httpx.AsyncClient and write await client.get(url). Replace time.sleep(1) with await asyncio.sleep(1). If no async version exists, move the call off the loop with await asyncio.to_thread(fn).

Detecting blocking calls

Turn on asyncio debug mode. You can set PYTHONASYNCIODEBUG=1 or call loop.set_debug(True) at startup. Then set loop.slow_callback_duration, for example to 0.05 seconds. The default is 100 ms. Any callback that runs longer than this threshold is logged, together with the location of the code that held the loop.

Debug mode adds overhead and a lot of log output. Run it in development and staging under realistic load, not in production all the time.

import asyncio
import logging
import time
from contextlib import asynccontextmanager

import httpx
import requests
from fastapi import FastAPI

logging.basicConfig(level=logging.WARNING)


@asynccontextmanager
async def lifespan(app: FastAPI):
    loop = asyncio.get_running_loop()
    loop.set_debug(True)  # dev/staging only; same effect as PYTHONASYNCIODEBUG=1
    loop.slow_callback_duration = 0.05  # log anything holding the loop > 50 ms (default 0.1)
    app.state.http = httpx.AsyncClient(timeout=5.0)  # one shared client per worker
    yield
    await app.state.http.aclose()


app = FastAPI(lifespan=lifespan)
UPSTREAM = ""


@app.get("/before")
async def before():
    time.sleep(1)
    return requests.get(UPSTREAM, timeout=5).json()


@app.get("/after")
async def after():
    await asyncio.sleep(1)
    r = await app.state.http.get(UPSTREAM)
    return r.json()

Enables asyncio debug mode with a 50 ms slow-callback threshold at FastAPI startup, so a handler that calls time.sleep and requests gets logged, and shows the awaited asyncio.sleep and httpx.AsyncClient replacements.

Should you use async def or plain def endpoints with SQLAlchemy?

There are three ways to combine endpoints and database access, and only two of them are reasonable.

Choice Where the DB call runs Effect under load
async def + AsyncSession (asyncpg) Event loop, non-blocking Many concurrent requests per worker
Plain def + sync Session FastAPI's threadpool Concurrency capped by thread count
async def + sync calls Event loop, blocking One request at a time per worker

The third option is the worst of the three. FastAPI assumes an async def endpoint will not block, so it runs that endpoint directly on the loop. A sync query inside it stops every other request, health checks included, until the query returns. It also gets none of the threadpool isolation that a plain def endpoint would get automatically.

The async stack pays off for I/O-bound services that keep many slow requests in flight at once. For CPU-bound work, or for services with modest concurrency, plain def endpoints with a sync session are simpler and usually just as fast. Their throughput is limited by the database and the CPU, not by how requests wait.

You can call sync code from an async endpoint with run_in_executor or Starlette's run_in_threadpool. That is a valid escape hatch for occasional blocking calls. The threadpool has a fixed size, though. If you offload heavily, requests queue for a thread instead, so the bottleneck moves rather than disappears.

Async SQLAlchemy also costs more to develop with:

  • Greenlet edge cases: an implicit IO call outside the greenlet bridge raises MissingGreenlet.
  • Stricter loading rules: lazy loads fail instead of quietly issuing a query.
  • Harder debugging: stack traces run through the event loop and the greenlet layer.

Choose async SQLAlchemy only when you need its concurrency.

Who should use FastAPI with async SQLAlchemy?

Async SQLAlchemy fits teams whose services spend most of each request waiting on I/O rather than computing, and who already run the rest of the request path asynchronously. Typical cases:

  • API gateways and aggregation services that call several upstream HTTP services and a database per request, where most time is spent waiting.
  • Services with long-lived or slow connections, such as WebSockets, server-sent events or long polling, where holding one thread per open connection would be wasteful.
  • High-concurrency, low-CPU endpoints where many requests are in flight on each worker and the database is reached through an async driver like asyncpg.
  • Codebases that are already async end to end, with async HTTP clients, async caches and async message consumers, so the database layer is not the only async piece.

It also suits teams willing to adopt the discipline it requires: explicit eager loading, one session per unit of work, no sync IO in async def handlers, and tests that run against a real async database. If the team will review for those rules, the extra complexity is manageable.

When should you avoid async SQLAlchemy?

Avoid it when the concurrency it provides does not match where your service spends its time, or when the codebase cannot keep the event loop free of blocking calls.

  • CPU-bound workloads. Report generation, heavy serialization, image processing or data transformation keep the loop busy regardless of how the database is accessed. Plain def endpoints, or moving the work to a separate process or job queue, are a better fit.
  • Modest traffic. If a few dozen threads in FastAPI's threadpool comfortably cover peak concurrency, sync SQLAlchemy in def endpoints gives the same practical throughput with simpler code and clearer stack traces.
  • Heavy dependence on sync-only libraries. If many calls go through SDKs or drivers with no async version, you end up wrapping them in asyncio.to_thread or run_in_threadpool. At that point you carry async complexity while still being bounded by the threadpool.
  • ORM models built around lazy loading. Large existing models that rely on implicit relationship loading throughout templates, serializers or business logic will raise MissingGreenlet in many places. Migrating means auditing every access path for eager loading, which may cost more than it returns.
  • Databases or drivers without solid async support. The async stack depends on an async DBAPI driver. If your database's async driver is immature or missing features you rely on, stay on the sync driver.
  • Teams new to asyncio. One blocking call in a hot path stalls every request on a worker. Without debug-mode checks in staging and code review for blocking calls, those regressions reach production easily.

What are the alternatives to async SQLAlchemy in FastAPI?

  • Sync SQLAlchemy with plain def endpoints. FastAPI runs these in its threadpool, so a blocking query only occupies one thread. You keep the full ORM with normal lazy loading and simpler debugging. Concurrency per worker is capped by the thread count, which you can offset by running more workers, as long as the total connection count stays within the database's limit.
  • Mixed endpoints in one app. Use async def with an AsyncSession for the few high-concurrency, I/O-heavy routes and def with a sync Session for the rest. This requires two engines and two session dependencies, and each engine has its own pool, so count both when sizing connections.
  • SQLAlchemy Core with AsyncEngine, without the ORM. Executing select(), insert() and text() statements through AsyncConnection avoids lazy loading and identity-map state entirely, so MissingGreenlet from attribute access cannot happen. You give up ORM conveniences such as relationship mapping and unit-of-work change tracking.
  • The async driver directly. Using asyncpg's own connection pool and query API removes the greenlet bridge and the ORM layer. You write SQL by hand and map rows yourself, and you take on transaction and pool management that SQLAlchemy would otherwise handle.
  • Offloading slow or blocking work. When the real problem is a few slow operations, moving them to a background worker process or job queue keeps request handlers short, whichever database layer you use.

How do you scope an AsyncSession to a single request?

Start with one engine per process. Call create_async_engine with a postgresql+asyncpg:// URL so SQLAlchemy uses asyncpg as the driver. Then build an async_sessionmaker bound to that engine with expire_on_commit=False. Without that setting, attributes expire after commit, and the next access tries to reload them. In async code that reload is an implicit I/O call, which fails.

The dependency is an async generator. It opens a session with async with SessionLocal() as session:, then yields it inside a try. If the endpoint returns normally, it awaits session.commit(). If an exception propagates, it awaits session.rollback() and re-raises so FastAPI still produces the error response. The async with block closes the session either way, which returns the connection to the pool. Endpoints declare session: AsyncSession = Depends(get_session) and never create or close sessions themselves.

This ownership rule saves debugging time. Handlers cannot forget to close a session, cannot commit halfway through and leave the transaction in an unclear state, and cannot leak a connection on an error path. The lifecycle lives in one function you review once, so a reviewer only needs to check a single place.

The cost is that the connection stays checked out for the whole request. Suppose a handler awaits a slow HTTP call after its first query. It holds a pooled connection, often idle in an open transaction, the entire time, and that lowers effective pool capacity. For those endpoints, inject the sessionmaker instead of a session and open short async with session.begin(): blocks only around the database work.

from collections.abc import AsyncIterator

from fastapi import Depends, FastAPI
from sqlalchemy import text
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine

engine = create_async_engine(
    "postgresql+asyncpg://app_user:change-me@db.internal:5432/appdb",
    pool_size=10,
)
SessionLocal = async_sessionmaker(engine, expire_on_commit=False)

app = FastAPI()


async def get_session() -> AsyncIterator[AsyncSession]:
    # The only place a session is created, committed, rolled back or closed.
    async with SessionLocal() as session:
        try:
            yield session
            await session.commit()  # endpoint returned normally
        except Exception:
            await session.rollback()  # undo partial work on any error
            raise  # let FastAPI build the error response
    # Leaving `async with` closes the session and returns the connection.


@app.get("/orders/{order_id}")
async def read_order(order_id: int, session: AsyncSession = Depends(get_session)):
    # Handlers use the session but never open or close it.
    result = await session.execute(
        text("SELECT id, status FROM orders WHERE id = :id"), {"id": order_id}
    )
    row = result.one_or_none()
    return {"id": row.id, "status": row.status} if row else {"id": order_id, "status": None}

Configures an asyncpg-backed engine and async_sessionmaker, then injects a per-request AsyncSession through a yield dependency that commits on success, rolls back on error and always closes the session.

What causes SQLAlchemy session leaks in FastAPI, including in background tasks?

A session held open across slow awaits is only one way to tie up pooled connections. The leak patterns below cause the same pool starvation, and they are harder to spot.

A module-level or global session is shared by every request. Its transaction never cleanly ends, and one failed request leaves it in a rolled-back state that breaks the requests after it. A session captured in a closure, such as a callback or cached function, outlives the request that created it and keeps its connection checked out. A session opened manually without try/finally or async with skips close() when an exception is raised, so the connection returns to the pool only when garbage collection runs, if it returns at all.

AsyncSession is not safe for concurrent use. If you pass one session to several coroutines under asyncio.gather, they interleave operations on a single connection. asyncpg rejects this with "another operation is in progress", and if it slips through, the session's state can be corrupted.

Background tasks run after the response is generated. The point at which a yield dependency's teardown runs relative to the response and to background tasks has changed between FastAPI releases. Code that reuses the request's session in a background task therefore depends on timing it does not control. The session may already be closed, or it may be held open until the task finishes. The fix in both cases is to pass IDs rather than ORM objects, and to open a fresh session from the sessionmaker inside the task.

Anti-pattern Symptom Fix
Global session Cross-request state, stuck transactions Session per request via dependency
Session in closure Connections held indefinitely Pass the sessionmaker, not the session
No close on error Pool timeouts under load async with the session
Shared session in gather "another operation is in progress" One session per task
Request session in background task Closed-session errors or a held connection New session inside the task
import asyncio

from fastapi import BackgroundTasks, Depends, FastAPI
from sqlalchemy import text
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine

engine = create_async_engine("postgresql+asyncpg://app:change-me@db.internal:5432/shop")
SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
app = FastAPI()

async def get_session():
    # One session per request; async with guarantees close() on every path, including errors.
    async with SessionLocal() as session:
        yield session

async def mark_receipt_sent(order_id: int) -> None:
    # Post-response work opens its own session instead of borrowing the request's.
    async with SessionLocal() as session, session.begin():
        await session.execute(text("UPDATE orders SET receipt_sent = true WHERE id = :id"), {"id": order_id})

async def count_by_status(status: str) -> int:
    # Each concurrent task gets a private session (and connection).
    async with SessionLocal() as session:
        result = await session.execute(text("SELECT count(*) FROM orders WHERE status = :s"), {"s": status})
        return result.scalar_one()

@app.post("/orders/{order_id}/complete")
async def complete(order_id: int, tasks: BackgroundTasks, session: AsyncSession = Depends(get_session)):
    async with session.begin():
        await session.execute(text("UPDATE orders SET status = 'complete' WHERE id = :id"), {"id": order_id})
    # Pass the ID, not the session or an ORM object.
    tasks.add_task(mark_receipt_sent, order_id)
    return {"id": order_id, "status": "complete"}

@app.get("/orders/stats")
async def stats():
    # Never gather over one shared AsyncSession; each coroutine opens its own.
    pending, complete = await asyncio.gather(count_by_status("pending"), count_by_status("complete"))
    return {"pending": pending, "complete": complete}

A per-request session dependency, a background task that opens a fresh session from the sessionmaker using only the order ID, and asyncio.gather where each concurrent coroutine gets its own AsyncSession.

How do you prevent lazy-loading errors with async SQLAlchemy?

In async SQLAlchemy, touching an unloaded relationship triggers a synchronous load that cannot run outside the greenlet bridge, so it fails with MissingGreenlet. The fix is to decide what to load when you write the query and not let attribute access fetch data implicitly.

Put the loading strategy in the select() itself. selectinload(User.orders) issues a second SELECT ... WHERE user_id IN (...), and joinedload(Order.customer) adds a JOIN to the same statement. Configure async_sessionmaker(..., expire_on_commit=False) so that reading attributes after commit() does not trigger a reload. When you need current database state, such as server defaults or trigger-set columns, call await session.refresh(obj, attribute_names=[...]) explicitly.

To make mistakes visible, set lazy="raise" on relationships or add raiseload("*") to queries. A forgotten eager load then raises a clear error in development and does not stay hidden until production traffic hits it. For the rare case where on-demand loading is right, the AsyncAttrs mixin lets you write await obj.awaitable_attrs.orders, which makes the I/O explicit in the code.

Strategy Queries Main cost Use when
selectinload 1 extra per relationship Extra round trips Collections (one-to-many)
joinedload Same query Row multiplication on collections Many-to-one, single objects
expire_on_commit=False None Objects may go stale versus the DB Returning objects after commit
refresh() 1 per call Explicit round trip Need server-generated values
lazy="raise" / raiseload None Must declare every load Catching implicit I/O early
awaitable_attrs 1 per access N+1 risk in loops Deliberate, occasional access

How should you size the connection pool and observe it in production?

Each engine owns its own pool, so the real ceiling is multiplied across every process. pool_size is the number of connections kept open. max_overflow is how many extra connections can open under burst. pool_timeout is how long a request waits for a free connection before raising. pool_pre_ping tests a connection on checkout, so connections dropped by the server or a load balancer are replaced instead of failing the request.

Illustrative estimate. Assume 4 Uvicorn workers per pod, 6 replicas, pool_size=10, and max_overflow=5. That is 4 × 6 × 15 = 360 possible connections. If Postgres has max_connections=200 with 10 reserved for superuser and maintenance, only 190 are available. During a burst or a rolling deploy, when old and new pods overlap, connection attempts start failing. Size the pool down from the database's limit, not up from a single process's latency.

A larger pool does not fix leaks or blocking calls. It only delays the symptoms. A leaked session or a blocked loop holds connections longer, so a bigger pool absorbs the problem until replicas scale out, and then the total crosses max_connections.

External poolers such as PgBouncer in transaction mode let many clients share few server connections. Transaction mode breaks asyncpg's prepared-statement cache, because the next statement may run on a different backend. Disable it by passing statement_cache_size=0 through connect_args.

Catch these problems before production:

  • Run tests against a real async database, not SQLite.
  • Assert that engine.pool.status() shows zero checked-out connections after each test.
  • Compare the pool's view with the open-connection counts in pg_stat_activity.
  • Set statement_timeout so a slow query raises an error instead of silently holding a connection.

A leak then shows up as a failing test or a rising count on a dashboard, before it causes an incident.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to fastapi async sqlalchemy, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a route's URL or method automatically notifies the services that consume it — no hunting through repos for callers.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Consumers learn about a breaking change at review time rather than from production errors.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.