How do create_async_engine, async_sessionmaker, and AsyncSession fit together?
The stack has four layers, each with a different lifetime.
create_async_enginebuilds anAsyncEnginefrom a URL such aspostgresql+asyncpg://.... The engine owns the connection pool, the set of open asyncpg connections that gets reused across requests.async_sessionmakeris a factory bound to that engine. It holds configuration likeexpire_on_commitand creates sessions on demand.AsyncSessionis 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.
selectinloadissues one extraSELECT ... WHERE id IN (...)per relationship and suits collections.joinedloaduses a JOIN in the same statement and suits many-to-one relationships. Settinglazy="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=5andmax_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_connectionsis 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
AsyncSessionper request via a dependency - Eager loading (
selectinload/joinedload) where relationships are read - (pool_size + max_overflow) × workers × replicas below
max_connections pool_recycleandpool_pre_pingset below server and load-balancer idle timeoutsNullPoolor disabled prepared-statement caching behind a transaction-mode poolerawait 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.