Using expire_on_commit=False in FastAPI Dependencies

Set expire_on_commit=False in async_sessionmaker and your FastAPI responses will serialize ORM instances correctly after commit — without it, every attribute read after await session.commit() raises MissingGreenlet because SQLAlchemy tries a synchronous lazy reload that has nowhere to run. This page is part of the guide to integrating SQLAlchemy async with FastAPI and Starlette, which covers the full request-scoped dependency lifecycle this one setting slots into.

Quick Answer

# WRONG — default expire_on_commit=True causes MissingGreenlet after commit
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession

engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")

# Omitting expire_on_commit means it defaults to True — dangerous in async FastAPI
bad_factory = async_sessionmaker(engine, class_=AsyncSession)


# CORRECT — expire_on_commit=False keeps in-memory attribute values after commit
good_factory = async_sessionmaker(
    engine,
    class_=AsyncSession,
    expire_on_commit=False,  # This one setting prevents the post-commit MissingGreenlet
)

In a FastAPI route that returns an ORM model (or one that Pydantic validates via model_validate), the response serializer reads instance attributes after the dependency's commit fires. With the default expire_on_commit=True, those attributes are expired, triggering a lazy SELECT that raises MissingGreenlet. With expire_on_commit=False, the pre-commit in-memory values remain available for as long as the Python object is referenced. This flag belongs alongside the rest of your async engine and connection pool configuration, since it is a property of the async_sessionmaker you build there.

Execution Context & Async Workflow Integration

Why SQLAlchemy expires attributes by default

SQLAlchemy's identity map tracks every attribute on every ORM instance. After a commit(), the authoritative state of the row is in the database, not in Python memory. A DB trigger might have updated a timestamp. A DEFAULT expression might have set a column the Python code never touched. An advisory lock release might have allowed a concurrent UPDATE to change a value. To prevent stale reads on the next access, SQLAlchemy marks all attributes as expired after commit. The next attribute read then fetches a fresh value from the database.

In a synchronous session, expiry is harmless: user.email triggers a SELECT users WHERE id=? LIMIT 1, the value is returned, and execution continues. In an AsyncSession, however, the lazy SELECT cannot run synchronously. The greenlet frame that managed the async DBAPI bridge was torn down when the session's async with session.begin() context exited. Attempting a lazy SELECT at that point raises:

sqlalchemy.exc.MissingGreenlet: greenlet_spawn has not been called;
can't call await_only() here. Was IO attempted in an unexpected place?

Post-commit expiry is only one of several ways to hit this error — the full set of MissingGreenlet root causes (wrong session type, lazy relationship access) is covered in the sibling page; here we focus on the FastAPI serialization timeline specifically.

The exact FastAPI commit timeline

Understanding precisely when commit fires relative to Pydantic serialization clarifies why this error appears in places that look unrelated to the database:

1. Route handler body completes and returns the ORM object, e.g. return user.
2. FastAPI prepares to send the HTTP response. Before serializing, it must exit the dependency context managers in reverse order.
3. The get_db_session dependency's async with session.begin() block exits — await session.commit() fires.
4. SQLAlchemy marks every attribute on every tracked instance (including user) as expired.
5. FastAPI calls the response_model validator, e.g. Pydantic's UserRead.model_validate(user).
6. Pydantic reads user.id → expired → lazy SELECT attempt → MissingGreenlet.

Step 6 is where the stack trace appears — inside Pydantic's validator, pointing at seemingly innocent attribute access. Developers are frequently confused because the traceback shows no obvious database code; the error appears to originate in the serialization layer. The timing of step 3 is dictated by where your transaction and commit boundary sits — moving the commit outside the request-serving path is another way to sidestep the expiry, but expire_on_commit=False is the simpler fix.

expire_on_commit=False eliminates step 4

With expire_on_commit=False configured in async_sessionmaker, step 4 is skipped entirely. Attributes retain their pre-commit Python-side values. When Pydantic reads user.id, user.email, user.created_at in step 6, it reads from the Python dictionary that has been in memory since the instance was loaded — no database I/O, no greenlet bridge required.

from contextlib import asynccontextmanager
from typing import AsyncGenerator

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

DATABASE_URL = "postgresql+asyncpg://user:pass@localhost:5432/appdb"

engine = create_async_engine(
    DATABASE_URL,
    pool_size=10,
    max_overflow=5,
    pool_pre_ping=True,
    pool_recycle=1800,
)

async_session_factory = async_sessionmaker(
    engine,
    class_=AsyncSession,
    expire_on_commit=False,  # retain attribute values after commit
)


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


app = FastAPI(lifespan=lifespan)


async def get_db_session() -> AsyncGenerator[AsyncSession, None]:
    async with async_session_factory() as session:
        async with session.begin():
            yield session  # commit fires when this context exits normally

The way this dependency scopes one AsyncSession per request — and returns its connection to the pool when the async with block exits — is governed by the AsyncSession lifecycle and scope management rules; expire_on_commit=False only changes what happens to attribute state at the commit inside that scope, not the scope itself.

Full route example showing safe post-commit attribute access

from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession

from myapp.models import User
from myapp.schemas import UserCreate, UserRead

router = APIRouter()


@router.post("/users/", response_model=UserRead, status_code=201)
async def create_user(
    payload: UserCreate,
    session: AsyncSession = Depends(get_db_session),
) -> User:
    user = User(email=payload.email, display_name=payload.display_name)
    session.add(user)
    await session.flush()  # assigns user.id from the DB sequence, within the txn
    # The dependency's context manager commits here when this function returns.
    # expire_on_commit=False means user.id and user.email remain readable.
    return user
    # Pydantic reads user.id, user.email, user.created_at after commit — all safe.

Without await session.flush() before returning, user.id would be None (the sequence value has not been assigned yet). Flush assigns the PK within the current transaction, so it is available when the function returns and Pydantic serializes the response.

Resolving Warnings, Errors & Common Mistakes

Advanced expire_on_commit=False Optimization

Refreshing only DB-generated columns

expire_on_commit=False keeps the pre-commit Python values. If the database populates a column that your Python code did not set — a DEFAULT NOW() timestamp, a trigger-computed field, a GENERATED ALWAYS AS column — that column's in-memory value will be stale after commit until you explicitly refresh it.

The pattern is to refresh only the specific column(s) you need, within the transaction, before the dependency commits:

from sqlalchemy.ext.asyncio import AsyncSession
from myapp.models import Invoice


async def create_invoice(session: AsyncSession, data: dict) -> Invoice:
    invoice = Invoice(**data)
    session.add(invoice)
    await session.flush()  # invoice.id assigned by sequence

    # The DB has a trigger that populates invoice.invoice_number.
    # Refresh only that column — still within the transaction.
    await session.refresh(invoice, attribute_names=["invoice_number"])

    # Dependency commits here on function return.
    # expire_on_commit=False keeps invoice.id, invoice.invoice_number, all other
    # attributes readable when Pydantic serializes the response.
    return invoice

session.refresh(obj, attribute_names=[...]) re-selects only the named columns from the database, within the current transaction, and populates them in the Python object. It is more efficient than session.refresh(obj) with no arguments, which re-fetches all columns.

Two session factories for different use cases

If your application mixes FastAPI request handlers (where expire_on_commit=False is correct) and background data pipelines (where you want fresh DB reads after every commit), declare two factories:

from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession, create_async_engine

engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db", pool_size=20)

# FastAPI request handlers: safe post-commit attribute access for serialization
request_session_factory = async_sessionmaker(
    engine,
    class_=AsyncSession,
    expire_on_commit=False,
)

# Background pipelines and scheduled jobs: always re-read from DB after commit
pipeline_session_factory = async_sessionmaker(
    engine,
    class_=AsyncSession,
    expire_on_commit=True,  # explicit; reload from DB on next access after commit
)

Using two named factories makes the intent explicit in code review and prevents a background pipeline developer from inadvertently relying on stale cached values. The same split matters when you run async SQLAlchemy inside Celery task workers, where each task should re-read committed state rather than trust pre-commit memory.

Testing with expire_on_commit=False

When writing pytest tests that use expire_on_commit=False sessions, test assertions after commit may not catch bugs where a DB constraint changes a value (e.g., a CHECK rounds a price, a trigger normalises a status string). The Python-side value looks correct because it was never refreshed. Two strategies:

Strategy 1 — Use expire_on_commit=True in test sessions. Tests re-read from the DB, catching constraint-driven changes. Accept that you must eager-load relationships explicitly in test queries.

Strategy 2 — Explicit refresh in assertion blocks. Keep expire_on_commit=False in the test session factory (to match production) but add await session.refresh(obj) in the assertion section of tests that check DB-computed values:

from decimal import Decimal

import pytest
from sqlalchemy.ext.asyncio import AsyncSession

from myapp.models import Product


@pytest.mark.asyncio
async def test_price_is_floored_by_constraint(session: AsyncSession) -> None:
    product = Product(name="Widget", price=Decimal("0.001"))
    session.add(product)
    await session.flush()

    # Force a re-read to catch any DB-side CHECK constraint rounding
    await session.refresh(product)
    assert product.price >= Decimal("0.01"), "Price floor constraint not applied"

Per-session override without changing the factory

If you need expire_on_commit=False on a single session without changing the factory default, set it on the instance:

async with async_session_factory() as session:
    session.expire_on_commit = False  # override for this session only
    async with session.begin():
        ...

Setting it before any objects are loaded ensures all instances in this session are governed by the new setting. This technique is useful in test fixtures that need to override the application's pipeline factory setting for a specific test case.

Frequently Asked Questions

Related

• Integrating SQLAlchemy Async with FastAPI and Starlette — parent guide covering the full dependency injection lifecycle that this setting is part of.
• Fixing GreenletSpawnError in Async SQLAlchemy Workflows — all MissingGreenlet root causes, not only the post-commit expiry case covered here.
• Configuring Async Engines and Connection Pools — the full engine and async_sessionmaker configuration reference these settings live in.
• AsyncSession Lifecycle and Scope Management — how per-request session scoping and pool return interact with commit-time attribute state.