How does SQLAlchemy's async engine actually work, and why does MissingGreenlet happen?

This guide is for backend and platform engineers running async FastAPI services against a relational database, where most sqlalchemy async session fastapi bugs trace back to one design decision.

AsyncEngine and AsyncSession are not a separate async ORM. They are thin wrappers around the ordinary synchronous Engine and Session. When you await session.execute(...), SQLAlchemy runs the sync ORM code inside a greenlet. When that code reaches the driver and needs I/O, the greenlet hands control back to the event loop, which awaits the async driver (asyncpg, aiosqlite, and so on), then resumes the greenlet with the result. The ORM's unit of work, identity map and loading logic stay unchanged. Only the I/O boundary is async.

await session.execute(stmt)
        │
        ▼
AsyncSession ──► greenlet bridge ──► sync Session / ORM ──► driver adapter ──► async driver ──► DB
                  (I/O allowed only in this context)

user.orders   (plain attribute access, no await)
        │
        ▼
sync Session lazy load ──► driver adapter ──► no greenlet context ──► MissingGreenlet

Plain attribute access cannot be awaited. If user.orders was never loaded, or user.name was expired by a commit, touching it makes the sync Session try to emit SQL with no greenlet context to suspend. SQLAlchemy cannot block the event loop safely, so it raises MissingGreenlet. The fix is never to wrap the access. Load what you need inside an awaited call, or make implicit loads impossible.

Async raises concurrency, not database throughput. A single worker can keep many requests in flight while they wait on I/O. Every query still costs the database the same amount of work, and the connection pool still caps how many queries run at once.

 EVENT LOOP (asyncio)                   GREENLET (I/O may suspend here)
┌──────────────────────────┐            ┌─────────────────────────────────┐
│ await session.execute()  │──spawn────►│ sync Session / ORM              │
│                          │            │ unit of work, identity map,     │
│                          │            │ loaders, autoflush              │
│                          │            │          │                      │
│                          │            │          ▼                      │
│ await driver ◄──► DB     │◄──switch───│ driver adapter needs I/O        │
│ other requests run       │            │                                 │
│                          │───resume──►│ adapter gets rows, ORM builds   │
│ result returned to caller│◄──return───│ objects; greenlet finishes      │
└──────────────────────────┘            └─────────────────────────────────┘

 OUTSIDE ANY AWAITED CALL (no greenlet context)
┌──────────────────────────┐
│ user.orders   (no await) │──► sync Session lazy load ──► driver adapter
└──────────────────────────┘                                    │
               raise MissingGreenlet ◄── no greenlet context ◄──┘

An awaited AsyncSession call runs the sync ORM inside a greenlet that can switch to the event loop to await the async driver, while plain attribute access that triggers a lazy load has no greenlet to suspend and raises MissingGreenlet.

How does it work across a full FastAPI request?

Putting the pieces together, one request flows like this:

  1. At startup, the process creates one AsyncEngine, which owns the connection pool, and one async_sessionmaker bound to it.
  2. When a request arrives, FastAPI resolves the get_session dependency. It creates an AsyncSession. No connection is checked out yet.
  3. The first awaited database call (execute, scalars, get, commit, refresh) makes the session check out a connection from the pool and begin a transaction. The ORM work runs in a greenlet and switches to the event loop each time the driver waits on the network. While it waits, the event loop serves other requests.
  4. Rows come back, and the ORM builds objects and stores them in the session's identity map. Relationships that were not eager loaded stay unloaded.
  5. The handler converts results into a response model while the session is still open. Any attribute it touches must already be loaded, or the access raises MissingGreenlet, or raiseload raises if you configured it.
  6. After the handler returns, the dependency commits on success. The async with exit then closes the session, which rolls back anything left open and returns the connection to the pool.

Every point where the database is touched is an await. Everything that happens without an await must work from memory alone. The rest of this guide follows from that rule.

Who should use SQLAlchemy async sessions with FastAPI?

The async session is a good fit when these conditions mostly hold:

  • Your endpoints are I/O-bound. Handlers spend most of their time waiting on the database, other HTTP services, or caches, and little time computing. That waiting time is what async lets a single worker overlap.
  • Your service already uses async def handlers and async clients for other I/O, such as an async HTTP client. Mixing a sync database layer into an otherwise async handler blocks the event loop on every query.
  • You need many concurrent in-flight requests per process, for example endpoints that fan out to slow upstreams or hold long-polling or streaming connections.
  • An async driver exists for your database and you are willing to depend on it, for example asyncpg for PostgreSQL or aiosqlite for SQLite.
  • Your team can work with explicit loading. You need to be comfortable declaring what each query loads up front and treating implicit lazy loads as bugs.

Teams starting a new FastAPI service with these characteristics are the main audience. So are teams migrating async handlers that currently make blocking ORM calls.

When should you avoid the async session?

Async SQLAlchemy adds a greenlet bridge, a stricter loading discipline and a new class of runtime errors. Skip it when that cost buys you nothing:

  • CPU-bound or mostly-compute endpoints. If a request spends its time in serialization, numerical work or template rendering, async I/O does not help, and the CPU work blocks the event loop anyway.
  • The database is the bottleneck. Async raises concurrency, not database throughput. If queries are slow or the pool is already saturated, more in-flight requests just queue for connections. Fix the queries, indexes or pool sizing first.
  • Codebases that rely heavily on lazy loading. If business logic walks relationships freely (order.customer.account.plan) across many modules, converting it means auditing every access path. Sync SQLAlchemy in plain def endpoints, which FastAPI runs in a threadpool, may be the cheaper, safer choice.
  • Large shared sync libraries. If most data access lives in sync code that is also used by workers, scripts or other services, you would route much of it through run_sync and gain little.
  • Batch jobs, migrations and CLI scripts. These usually run one unit of work at a time. Sync sessions are simpler and give clearer stack traces.
  • No mature async driver for your database, or a deployment environment where installing the greenlet dependency is a problem.

A plain def handler with a sync Session is a legitimate FastAPI design, not a legacy one. Choose async because your workload needs overlapping I/O, not because the framework supports it.

What is the correct session lifecycle for SQLAlchemy async sessions in FastAPI?

The ownership model that holds up in production has three scopes. The process owns one AsyncEngine and one async_sessionmaker. Each request owns one AsyncSession. Service code owns nothing and borrows the session it is given.

Process scope: engine and sessionmaker

A db module creates the engine with create_async_engine and binds an async_sessionmaker to it. Both are cheap to share and expensive to recreate, because the engine holds the connection pool. The FastAPI lifespan handler calls await engine.dispose() on shutdown so pooled connections close cleanly instead of being dropped when the process exits.

Request scope: the dependency

get_session opens a session with async with sessionmaker() as session: and yields it. The context manager matters. If a handler raises or the client disconnects, the async with exit still runs close(), which returns the connection to the pool. A bare session = sessionmaker() followed by yield skips that guarantee whenever the cleanup line is never reached.

Service scope: explicit arguments

Service functions take session: AsyncSession as a parameter. This keeps them testable, makes transaction boundaries visible at the call site, and stops helpers from opening hidden sessions of their own.

Committing in the dependency

Calling commit() after the yield ties one transaction to one request, which is simple. The cost is that the connection stays checked out for the whole request. A slow third-party call or a long streaming response holds a pooled connection the entire time, even while it does no database work. For those endpoints, commit inside the service before the slow part. Also check how your FastAPI version orders dependency teardown relative to streaming, because that ordering has changed over time.

from collections.abc import AsyncIterator
from contextlib import asynccontextmanager

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:change-me@db.internal:5432/app", pool_size=10)
SessionLocal = async_sessionmaker(engine, expire_on_commit=False)  # avoid lazy refresh after commit

@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    yield
    await engine.dispose()

app = FastAPI(lifespan=lifespan)

async def get_session() -> AsyncIterator[AsyncSession]:
    async with SessionLocal() as session:
        yield session
        # Only reached on success. On error, close() rolls back the open transaction.
        # Trade-off: the pooled connection stays checked out until this line runs.
        await session.commit()

async def count_orders(session: AsyncSession, customer_id: int) -> int:
    result = await session.execute(
        text("SELECT count(*) FROM orders WHERE customer_id = :cid"), {"cid": customer_id}
    )
    return result.scalar_one()

@app.get("/customers/{customer_id}/order-count")
async def order_count(customer_id: int, session: AsyncSession = Depends(get_session)) -> dict:
    return {"count": await count_orders(session, customer_id)}

A minimal reference layout with a process-scoped engine and sessionmaker, engine disposal in the lifespan handler, a per-request get_session dependency wrapped in async with that commits after the yield, and a service function that receives the session as an explicit argument.

Where do async session leaks come from, and how do you spot them?

A leak here means a connection checked out of the pool and not returned in time. The usual sources are a session stored at module level or on app.state and reused across requests, a session created without async with so close() never runs on error paths, a background task that keeps using the request's session after the dependency has closed it, and a long transaction that holds its connection while it waits on unrelated I/O.

An AsyncSession is not safe for concurrent use. It keeps a single identity map and a single connection, and it tracks state for only one transaction. If you run asyncio.gather over two queries on the same session, both coroutines drive that state at the same time. You may get an error about the session already being busy, or you may get interleaved and corrupted state. Do not gather over the request session. Give each concurrent unit of work its own session from the async_sessionmaker, and do the same for each background task.

Leak pattern Symptom Fix
Shared module/app-state session Cross-request data bleed, concurrency errors Session per request via dependency
No async with Checkouts climb after exceptions Always use the context manager
Background task reuses request session Errors on a closed session, or a held connection Task opens its own session
gather on one session Busy-session errors, inconsistent results One session per concurrent task
Long transactions Pool exhaustion under load Commit before slow work

Under load, a leak surfaces as a pool TimeoutError once pool_size plus max_overflow connections are all checked out and pool_timeout expires. Setting pool_pre_ping discards stale connections, but it does not fix leaks. To confirm a leak, set echo_pool on the engine or raise the sqlalchemy.pool logger to DEBUG. Then look for checkouts that never get a matching return.

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/appdb",
    pool_size=5,         # steady-state connections kept in the pool
    max_overflow=10,     # extra connections allowed during bursts
    pool_timeout=30,     # seconds to wait for a free connection before TimeoutError
    pool_pre_ping=True,  # discards stale connections; does NOT fix leaks
    echo_pool="debug",   # logs every checkout/checkin so unreturned checkouts stand out
)
SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
app = FastAPI()

async def get_session():
    async with SessionLocal() as session:  # closed on success and on error
        yield session

async def scalar(sql: str):
    async with SessionLocal() as s:  # one session per concurrent unit of work
        return (await s.execute(text(sql))).scalar_one()

async def write_audit(user_id: int):
    async with SessionLocal() as s, s.begin():  # background task opens its own session
        await s.execute(text("INSERT INTO audit_log (user_id) VALUES (:u)"), {"u": user_id})

@app.get("/stats/{user_id}")
async def stats(user_id: int, bg: BackgroundTasks,
                session: AsyncSession = Depends(get_session)):
    name = (await session.execute(text("SELECT name FROM users WHERE id = :u"), {"u": user_id})).scalar_one()
    # WRONG: await asyncio.gather(session.execute(q1), session.execute(q2))
    orders, users = await asyncio.gather(
        scalar("SELECT count(*) FROM orders"),
        scalar("SELECT count(*) FROM users"),
    )
    bg.add_task(write_audit, user_id)  # pass IDs, never the request session
    return {"name": name, "orders": orders, "users": users}

A FastAPI app with explicit pool settings and pool logging, a request-scoped session dependency, a separate session per gathered query, and a background task that opens its own session instead of reusing the request's.

Should you set expire_on_commit=False?

By default, AsyncSession.commit() expires every object in the identity map. Expiring marks loaded attributes as stale, so the next attribute access makes SQLAlchemy issue a SELECT to reload the row. In synchronous code that refresh is invisible. In async code it is implicit I/O outside an await, so it raises MissingGreenlet. The usual trigger is a handler that commits, returns the ORM object, and lets FastAPI serialize it. Serialization reads user.email after the commit, and the request fails.

The common fix is to configure the factory with async_sessionmaker(engine, expire_on_commit=False). Objects then keep their loaded values after commit, and reads hit memory, not the database.

What you give up

The in-memory state becomes a snapshot from before the commit. Values the database produced during or after the flush never reach the object unless you ask for them. That includes server defaults, onupdate columns computed server-side, trigger-modified fields, and changes committed concurrently by other transactions. A response can show updated_at as None, or a status that a trigger has already rewritten.

Choosing between them

expire_on_commit=False is a sensible default for request-scoped sessions. In that setup the session is discarded at the end of the request, and the response mostly echoes what the client sent.

When the response depends on database-generated state, call await session.refresh(obj) after the commit, or name specific columns with attribute_names. This makes the round trip explicit and awaited. For newly generated columns, server_default with eager_defaults on the mapper can also return values during the flush, so no extra query is needed.

from datetime import datetime

from fastapi import Depends, FastAPI
from sqlalchemy import func
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

engine = create_async_engine("postgresql+asyncpg://app:change-me@localhost:5432/appdb")
SessionLocal = async_sessionmaker(engine, expire_on_commit=False)

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str]
    # Generated by the database, so the ORM never loaded it during the INSERT.
    created_at: Mapped[datetime] = mapped_column(server_default=func.now())

async def get_session():
    async with SessionLocal() as session:  # request-scoped, closed after the response
        yield session

app = FastAPI()

@app.post("/users")
async def create_user(email: str, session: AsyncSession = Depends(get_session)):
    user = User(email=email)
    session.add(user)
    await session.commit()
    # user.id and user.email are still in memory: no refresh, no MissingGreenlet.
    # created_at was never loaded; touching it now would lazy-load and fail.
    # Fetch only the server-generated column, explicitly and awaited.
    await session.refresh(user, attribute_names=["created_at"])
    return {"id": user.id, "email": user.email, "created_at": user.created_at}

A request-scoped async_sessionmaker with expire_on_commit=False, plus a targeted await session.refresh() for a server-default column the in-memory object would otherwise lack.

When should you use selectinload, joinedload, or raiseload?

Eager loading is the main fix for lazy-load errors because it moves every relationship fetch into the awaited execute() call, so nothing is left for an attribute access to trigger later. The right strategy depends on what each endpoint returns, so set it on the query with loader options, for example select(Order).options(selectinload(Order.items), joinedload(Order.customer)), rather than once for the whole model.

Strategy SQL emitted Best for Cost
selectinload Parent query, then one SELECT ... WHERE key IN (...) per relationship One-to-many and many-to-many collections One extra round trip per relationship loaded
joinedload Single query with a LEFT OUTER JOIN Many-to-one and one-to-one On collections, parent rows repeat once per child. The result must be de-duplicated with .unique()
raiseload None. Access raises an error Catching relationship access you did not plan for Every needed relationship must be loaded explicitly

raiseload works as a per-query option, and raiseload("*") covers all unspecified relationships. You can also make it the default with relationship(..., lazy="raise"). Query-level selectinload or joinedload still overrides that default. In an async codebase, a raise default turns a MissingGreenlet that appears somewhere in serialization into a clear error that names the attribute.

There are trade-offs in both directions. If you eager load everything "to be safe", you over-fetch: list endpoints pull collections the response schema never serializes, and memory grows with each row. A blanket raise default creates friction, and teams under deadline often respond by adding selectinload to every query, which brings back the same over-fetching. Keep loader options next to the response model they serve. Review them when the schema changes, not when an error appears.

What are the alternatives when you need deferred loading or sync code?

Sometimes the access pattern is conditional and you cannot know at query time what you will need. SQLAlchemy gives you three explicit escape hatches for those cases.

  • await session.refresh(obj, attribute_names=["orders"]) loads only the named attributes for an object already in the session. It suits a branch that needs one relationship on a rare path.
  • The AsyncAttrs mixin. Add it to your declarative base, for example class Base(AsyncAttrs, DeclarativeBase). You can then write orders = await user.awaitable_attrs.orders. The mixin wraps a lazy load in an awaitable, so the access works inside the event loop without raising MissingGreenlet.
  • await session.run_sync(fn) passes a synchronous Session to fn and runs it in the greenlet context. Use it for code that must stay synchronous, such as an existing helper library or a function shared with a sync worker. Inside fn, lazy loading works as it does in sync code.

None of these restores implicit IO. Each one is an await that you can see at the call site, and that visibility is the reason they are safe to use.

They become a problem when they turn into the default. Picture an awaitable_attrs access inside a loop over fifty rows. That is fifty round trips, the same N+1 pattern that eager loading was meant to remove. Scattered refreshes also make the IO hard to audit, because you can no longer read one query and know what a request costs.

Treat these calls as exceptions:

  • Keep them out of loops.
  • Leave a comment explaining why eager loading did not fit.
  • If the same escape hatch shows up on a hot path, move that relationship into the query's loader options.

How do you serialize and test async sessions to save engineering time?

The safest serialization boundary is the session boundary. If a route returns an ORM object, FastAPI serializes it after the handler returns. By then the dependency may already have closed the session. Any attribute that was never loaded then triggers lazy I/O outside an async context, or touches a detached instance. The result is MissingGreenlet or DetachedInstanceError, and it shows up only for the response shapes that happen to reach an unloaded relationship.

Convert to a Pydantic model or plain dict inside the handler, while the session is still open. Build the response model from the ORM object with attribute-based validation enabled, and return that. Every attribute access now happens in a context you control. Combined with raiseload, a missing eager load fails at that line, not somewhere inside the framework.

For tests, open a connection, begin an outer transaction, and bind the test's session to that connection. Configure the session so its commits become savepoints. Roll back the outer transaction in teardown. Each test sees a clean database without truncating tables.

NullPool fits two cases:

  • Test runs, where you want connections closed deterministically.
  • Deployments behind an external pooler, where pooling twice causes problems.

Be aware of what it costs in tests. Neither NullPool nor a single shared connection can exhaust a pool, contend for connections, or reuse a connection a leaked session left dirty. Run at least one suite against a small, real pool under concurrent requests.

This is where the time savings come from. Explicit session ownership, raiseload, and in-session serialization turn intermittent production failures into deterministic test failures. A failing test with a stack trace pointing at the exact attribute is much faster to fix than a production incident that appears only under load.

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 sqlalchemy async session fastapi, 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.