How do create_async_engine, async_sessionmaker, and AsyncSession fit together?

The stack has four layers, each with a different lifetime.

  • create_async_engine builds an AsyncEngine from a URL such as postgresql+asyncpg://.... The engine owns the connection pool, the set of open asyncpg connections that gets reused across requests.
  • async_sessionmaker is a factory bound to that engine. It holds configuration like expire_on_commit and creates sessions on demand.
  • AsyncSession is a short-lived unit of work. It is cheap to create. It checks out a pool connection only when it first needs one, and returns it when the transaction ends or the session closes.
 Replica A                          Replica B
 ├─ Worker 1: engine + pool         ├─ Worker 1: engine + pool
 │    ├─ request → AsyncSession ─┐  │    └─ ...
 │    └─ request → AsyncSession ─┴→ checkout from pool
 └─ Worker 2: engine + pool         └─ Worker 2: engine + pool

Create the engine once per process in the FastAPI lifespan, and call await engine.dispose() on shutdown. If you build an engine per request, you pay a TCP and auth handshake on every request, pooling stops doing anything, and abandoned connections pile up on the server. Disposing on shutdown closes sockets cleanly instead of leaving the database to time them out.

Each worker needs its own engine. Connections are sockets with protocol state, and asyncpg connections are tied to the event loop that created them. An engine inherited across fork shares those sockets between processes and corrupts them. The lifespan runs inside each worker, so creating the engine there avoids the problem.

This stack is for I/O-bound services with many concurrent requests that spend most of their time waiting on the database or the network. For low-concurrency or CPU-heavy workloads, sync SQLAlchemy is simpler and usually just as fast.

from contextlib import asynccontextmanager
from typing import AsyncIterator

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

DATABASE_URL = "postgresql+asyncpg://app_user:change-me@db.internal:5432/app"


@asynccontextmanager
async def lifespan(app: FastAPI):
    # Runs inside each worker process, on that worker's event loop,
    # so every worker gets its own engine and pool (nothing crosses fork).
    engine = create_async_engine(DATABASE_URL, pool_size=5, max_overflow=5)
    app.state.sessionmaker = async_sessionmaker(engine, expire_on_commit=False)
    yield
    # Close pooled sockets cleanly instead of letting the server time them out.
    await engine.dispose()


app = FastAPI(lifespan=lifespan)


async def get_session(request: Request) -> AsyncIterator[AsyncSession]:
    # One short-lived session per request; it checks out a pool connection
    # only when first used and returns it when the block exits.
    async with request.app.state.sessionmaker() as session:
        yield session


@app.get("/health/db")
async def db_health(session: AsyncSession = Depends(get_session)) -> dict:
    result = await session.execute(text("SELECT 1"))
    return {"db": result.scalar_one()}

A FastAPI lifespan that creates one AsyncEngine and async_sessionmaker per worker process, disposes the engine on shutdown, and hands each request its own AsyncSession through a dependency.

How should you scope a FastAPI SQLAlchemy async session per request?

The standard pattern is a yield dependency that opens one AsyncSession per request from a module-level async_sessionmaker. Wrap the session in async with so it closes even when the endpoint raises. Closing releases the session's connection back to the pool and rolls back any transaction that was never committed. FastAPI injects the same session into every dependency that requests it within one request, so a request gets one session and at most one checked-out connection.

The design choice is where commit() lives.

Aspect Commit in the dependency Commit in endpoint or service layer
Endpoint code Shorter, with no transaction calls Each write path calls commit() or uses session.begin()
Transaction boundary Hidden, implied by request end Explicit and visible during code review
Partial failure All or nothing for the whole request You decide what to keep and what to roll back
Savepoints (begin_nested) Awkward, because the outer commit is out of reach Natural to compose
Multiple units of work per request Not supported Straightforward

Committing in the dependency works for simple CRUD services. Once a request needs to record a failure while discarding other work, the explicit style is easier to reason about.

Never share an AsyncSession across concurrent tasks, asyncio.gather calls, or requests. A session holds one connection and mutable identity-map state, and it is not safe for concurrent use. Two coroutines interleaving on it can trigger errors about operations already in progress, or they can silently mix their transaction state. If you need parallel queries, give each task its own session.

Background tasks run after the response is sent, when the request-scoped session has already closed. They should open a fresh session from the sessionmaker rather than capture the request's session.

from typing import AsyncIterator

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

# Module-level engine and factory, created once per process.
engine = create_async_engine("postgresql+asyncpg://app:change-me@db.internal:5432/orders")
SessionLocal = async_sessionmaker(engine, expire_on_commit=False)

app = FastAPI()


async def get_session() -> AsyncIterator[AsyncSession]:
    # One session per request. `async with` closes it even if the endpoint raises.
    # Closing returns the connection to the pool and rolls back uncommitted work.
    # This dependency never commits, so transaction boundaries stay in the endpoint.
    async with SessionLocal() as session:
        yield session


async def write_audit(order_id: int) -> None:
    # Runs after the response is sent, when the request session is already closed.
    # Open a new session here and commit it on exit with begin().
    async with SessionLocal.begin() as session:
        await session.execute(
            text("INSERT INTO audit_log (order_id, event) VALUES (:id, 'shipped')"),
            {"id": order_id},
        )


@app.post("/orders/{order_id}/ship")
async def ship_order(
    order_id: int,
    tasks: BackgroundTasks,
    session: AsyncSession = Depends(get_session),
):
    # The transaction boundary is explicit: it commits on exit and rolls back on error.
    async with session.begin():
        await session.execute(
            text("UPDATE orders SET status = 'shipped' WHERE id = :id"),
            {"id": order_id},
        )
    # Pass plain values to the background task, never the request-scoped session.
    tasks.add_task(write_audit, order_id)
    return {"status": "shipped"}

This example shows a yield dependency that opens and always closes one AsyncSession per request, an endpoint that commits explicitly, and a background task that opens its own session rather than reusing the request's.

Why does lazy loading fail with AsyncSession, and how do you fix it?

With a synchronous session, touching an unloaded relationship like order.items quietly issues a SELECT. Under AsyncSession, that same access happens in ordinary attribute-lookup code, which cannot await. SQLAlchemy runs async drivers such as asyncpg through a greenlet bridge that only works inside its own awaited calls. A lazy load triggered outside that context fails with a MissingGreenlet error instead of blocking the event loop. This usually surfaces in two places: after a query returns, or inside FastAPI's response serialization, which walks every attribute of an ORM object.

Fixes

  • Eager loading. Declare what you need in the query. selectinload issues one extra SELECT ... WHERE id IN (...) per relationship and suits collections. joinedload uses a JOIN in the same statement and suits many-to-one relationships. Setting lazy="raise" on relationships turns forgotten loads into immediate, obvious errors during development.
  • expire_on_commit=False. By default, commit expires every loaded attribute, so the next read triggers a refresh, which is another implicit load. Disabling expiry on the sessionmaker keeps the values readable after commit.
  • Return Pydantic response models. Convert ORM objects to response schemas while the session is still open. Serialization then never touches live ORM state.

Trade-offs

Applying eager loading everywhere replaces lazy-load failures with over-fetching. Chained joinedload on collections multiplies result rows, and each selectinload adds a round trip, even on endpoints that never read the data. With expire_on_commit=False, objects keep their values as of commit time. Code that treats those objects as current can act on stale data, for example by reading a column a trigger changed or a balance another transaction updated. When freshness matters, re-query or call await session.refresh(obj).

from fastapi import Depends, FastAPI
from pydantic import BaseModel, ConfigDict
from sqlalchemy import ForeignKey, select
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship, selectinload

engine = create_async_engine("postgresql+asyncpg://app:change-me@db:5432/shop")
# Values stay readable after commit, but they are a snapshot, not live data.
SessionLocal = async_sessionmaker(engine, expire_on_commit=False)

class Base(DeclarativeBase): pass

class Order(Base):
    __tablename__ = "orders"
    id: Mapped[int] = mapped_column(primary_key=True)
    # lazy="raise" makes a forgotten eager load fail loudly instead of attempting implicit I/O.
    items: Mapped[list["Item"]] = relationship(lazy="raise")

class Item(Base):
    __tablename__ = "items"
    id: Mapped[int] = mapped_column(primary_key=True)
    order_id: Mapped[int] = mapped_column(ForeignKey("orders.id"))
    sku: Mapped[str]

class ItemOut(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    sku: str

class OrderOut(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    items: list[ItemOut]

async def get_session():
    async with SessionLocal() as session:
        yield session

app = FastAPI()

@app.get("/orders/{order_id}", response_model=OrderOut)
async def read_order(order_id: int, session: AsyncSession = Depends(get_session)):
    # selectinload fetches the collection with one extra awaited SELECT ... WHERE order_id IN (...).
    stmt = select(Order).where(Order.id == order_id).options(selectinload(Order.items))
    order = (await session.execute(stmt)).scalar_one()
    # Convert while the session is open so serialization never touches live ORM state.
    return OrderOut.model_validate(order)

An async FastAPI endpoint that avoids MissingGreenlet errors by combining lazy="raise", selectinload eager loading, expire_on_commit=False, and conversion to a Pydantic response model before the session closes.

How big should the connection pool be across workers and replicas?

Each process owns its own pool, so the ceiling the database sees is multiplicative. The rule: (pool_size + max_overflow) × worker processes × replicas must stay below max_connections minus headroom for admin sessions, migrations, cron jobs, and other services that share the database. The pool's maximum is what counts, not its typical usage, because a burst can fill every pool at once.

Illustrative estimate

Assume these inputs:

  • pool_size=5 and max_overflow=5, so each process can open up to 10 connections.
  • Each pod runs 4 workers.
  • There are 3 replicas.
  • The rolling deploy surges by 1 pod.
  • max_connections is 200, with 20 reserved as headroom.
Scenario Pods Max app connections Budget (200 − 20)
Steady state 3 3 × 4 × 10 = 120 180
Rolling deploy overlap 4 4 × 4 × 10 = 160 180
Autoscale to 5 pods 5 200 180 (exceeded)

The deploy row is the one teams miss. During a rollout, old pods are still draining while new pods have already warmed their pools. If you only plan for steady state, you can exceed the limit during a routine release. The table also shows that the autoscaler's maximum replica count belongs in this calculation.

The trade-off

A large pool does not create database capacity. It lets more queries run concurrently, which hides application-side latency and moves contention into the database, where it shows up as lock waits and CPU saturation. A small pool protects the database, but under burst load requests queue for a connection and eventually hit pool_timeout. Size the pool from the database's sustainable concurrency, then measure the time requests spend waiting for a connection. No single number is correct for every workload.

What causes connection pool exhaustion and stale connections?

Most exhaustion incidents are not caused by too few connections. They come from connections held longer than the work requires. A session checks out a connection on its first query and keeps it until commit, rollback, or close. Every await between those points keeps that connection reserved while other requests wait in the queue.

Symptom Likely cause Fix
Requests stall, then fail at pool_timeout Session holds a connection across a slow external HTTP call Commit or close before the call; reopen afterwards
Errors in background work, or checked-out count creeping up Background task reuses the request-scoped session Give the task its own session from async_sessionmaker
Checked-out count never returns to baseline Sessions created outside a context manager and never closed Always use async with or a yield dependency
Intermittent "connection closed" errors after idle periods Database, load balancer, or proxy dropped idle connections Enable pool_pre_ping; set pool_recycle below the shortest idle timeout

Stale connections need two settings. pool_recycle replaces connections older than a given number of seconds. Set it below the smallest idle timeout anywhere on the path, whether that timeout lives on the database server, a load balancer, or a proxy. pool_pre_ping tests each connection at checkout and discards dead ones. It costs one extra round trip per checkout, and in return far fewer requests fail on a dead socket.

Async access does not make slow queries or CPU-bound work faster. It only lets the event loop serve other requests while waiting on I/O. If the database is already saturated, adding concurrency increases lock and I/O contention, and every query gets slower.

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/app",
    pool_size=10,
    max_overflow=5,
    pool_timeout=30,     # seconds a request waits for a free connection before raising
    pool_recycle=1800,   # keep below the shortest idle timeout on the path (DB, LB, proxy)
    pool_pre_ping=True,  # one extra round trip per checkout; discards dead connections
)
SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
app = FastAPI()

async def get_session():
    async with SessionLocal() as session:  # closed after the request, even on error
        yield session

async def audit(order_id: int) -> None:
    # Background work gets its own session; never reuse the request-scoped one.
    async with SessionLocal() as session:
        await session.execute(text("INSERT INTO audit_log (order_id) VALUES (:id)"), {"id": order_id})
        await session.commit()

@app.post("/orders/{order_id}/charge")
async def charge(order_id: int, tasks: BackgroundTasks, session: AsyncSession = Depends(get_session)):
    result = await session.execute(text("SELECT amount FROM orders WHERE id = :id"), {"id": order_id})
    amount = result.scalar_one()
    await session.commit()  # ends the transaction and returns the connection to the pool

    await asyncio.sleep(2)  # stand-in for a slow external HTTP call; no DB connection held

    # The next statement checks out a connection again, only for as long as it is needed.
    await session.execute(text("UPDATE orders SET status = 'charged' WHERE id = :id"), {"id": order_id})
    await session.commit()
    tasks.add_task(audit, order_id)
    return {"order_id": order_id, "amount": amount}

Configures pool_pre_ping and pool_recycle against stale connections, releases the connection before a slow external call, and gives a background task its own session instead of the request-scoped one.

When should you avoid in-process pooling, and what are the alternatives?

If an external pooler in transaction mode sits between your app and Postgres, a large in-process pool mostly duplicates its work. Each server connection is lent out per transaction, so the next transaction on the same client connection may run on a different backend. Use NullPool, or a small pool if you want to skip reconnecting through the pooler on every checkout. With asyncpg, also disable its prepared statement cache by setting statement_cache_size to 0 in connect_args. Otherwise a statement prepared on one backend gets executed on another, and the query fails.

NullPool makes connection accounting simple: open connections equal in-flight sessions. The cost is a full connection handshake on every checkout. You also lose session-level state, including prepared statements, advisory locks, SET commands, and temporary tables, because none of it survives past the transaction.

Approach Strength Cost
In-process QueuePool-style pool Cheap checkouts, session state works Pool size multiplies across workers and replicas
NullPool + external pooler One place to cap server connections Setup cost per checkout, no session-level features
Sync engine in a threadpool Mature drivers, simple debugging Threadpool size becomes a second limit to tune
Mixed sync and async engines Gradual migration Two pools, two configs, two failure modes

Mixing engines doubles the connection math you must get right. Each engine keeps its own pool, its own timeouts, and its own recycle settings. A leak in either one still counts against the same server limit.

Async SQLAlchemy is the wrong choice when your handlers mostly run long, heavy queries, or when the database is already the bottleneck. It is also a poor fit when your team depends on lazy loading. In those cases, a sync engine with bounded threads is easier to operate.

How can observability and lifecycle hygiene save engineering time?

Pool problems rarely show up in local testing because one developer never holds more than a handful of connections. They show up under load as latency spikes and timeouts that are hard to reproduce. A few minutes of instrumentation turns those incidents from multi-day investigations into a single query.

Watch the pool from the application

The QueuePool behind your engine exposes checkedout(), overflow() and size(). Export them as gauges on a timer. If checked-out connections climb while request rate stays flat, something is holding sessions too long, such as a background task or a missing async with. If overflow sits near its maximum, your pool math is wrong.

Enforce limits at the database

Set statement_timeout and idle_in_transaction_session_timeout on the database role. Then a runaway query or a forgotten transaction gets killed by Postgres instead of pinning a connection indefinitely. Pass a distinct application_name through asyncpg's server_settings so each service is identifiable.

Look from the server side

Filter pg_stat_activity by application_name and state = 'idle in transaction', ordered by xact_start. Old transactions with an unchanged query point directly at the leaking code path.

Checklist

  • One engine per process, created in lifespan
  • One AsyncSession per request via a dependency
  • Eager loading (selectinload/joinedload) where relationships are read
  • (pool_size + max_overflow) × workers × replicas below max_connections
  • pool_recycle and pool_pre_ping set below server and load-balancer idle timeouts
  • NullPool or disabled prepared-statement caching behind a transaction-mode pooler
  • await engine.dispose() on shutdown

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 sqlalchemy async session, 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.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

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.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • 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.