Performance checklist

In one sentence

Five things to check before you trust a FastAPI service under real concurrency. Each one maps to a demo with captured before-and-after numbers.

Tick items as you go. Progress is saved in this browser's local storage only. Nothing is sent anywhere, and the page works without it.

1. Event loop hygiene

• No synchronous I/O (`requests`, blocking file or DB drivers, `time.sleep`) inside any `async def` route or dependency.
• If you must call a sync library you cannot replace yet, wrap it in `loop.run_in_executor(...)` as a migration bridge, not a permanent fix.
• Verify with `py-spy record` under concurrent load, or `PYTHONASYNCIODEBUG=1`, and watch for "Executing ... took X seconds" warnings.

Demo: AP1. Three concurrent requests: 3.05 s blocking against 1.04 s async.

2. Dependency lifecycle

• Expensive objects (DB engines, HTTP clients, config) are created once, in the app lifespan, and handed out through `yield`-based `Depends()`. Never rebuilt per request.
• Use `Annotated[T, Depends(get_x)]` for shared singletons. Reserve `lru_cache` for pure, cheap factories.
• Verify with a latency benchmark comparing the dependency's endpoint against a lifespan-singleton equivalent.

Demo: AP2. 17.5 ms against 1.7 ms mean, about 10×, from rebuilding an engine per request.

3. ORM loading strategy

• Every relationship accessed in a response path is eager-loaded (`selectinload` or `joinedload`) in the query that fetches the parent. Never touched lazily inside a loop.
• Consider `lazy="raise"` on relationships in async models, so an accidental lazy touch fails loudly in development instead of degrading silently in production.
• Verify with `echo=True` and a query counter: one extra query per eager-loaded relationship, not one per row.

Demo: AP3. Plain attribute access crashes with MissingGreenlet. awaitable_attrs works but costs 6 queries against 2 for five orders.

4. Pydantic usage

• Validate directly from ORM objects with `ConfigDict(from_attributes=True)`. No manual dict construction, and no `model_dump()` followed by `model_validate()` round-trips.
• For data that never crosses a process or API boundary, skip Pydantic entirely. A `dataclass` or `TypedDict` is enough.
• Verify with `cProfile` over a realistic batch size. Look at the function-call count, not just wall time.

Demo: AP4. About 1.9× slower and about 1.8× more function calls, from a redundant validation round-trip.

5. Connection pool sizing

• `pool_size` and `max_overflow` are sized for your expected concurrency, not the driver's tutorial defaults (`pool_size=5, max_overflow=10`).
• `pool_timeout` is a deliberate choice. You know what "the pool is exhausted" looks like for your users.
• Verify with a locust run at realistic concurrency. Watch for `sqlalchemy.exc.TimeoutError: QueuePool limit ... reached`.

Demo: AP5. Same load, same code: 2.1% failures at 47.8 req/s with the undersized pool, against 0% failures at 179.3 req/s with the tuned pool.

Profiling toolkit

Tool	Use it for	Command
py-spy	Zero-instrumentation sampling profiler, flame graphs	py-spy record --pid <PID> -o out.svg
asyncio debug mode	Catching blocking calls inside async def	PYTHONASYNCIODEBUG=1 python app.py
cProfile and pstats	Function-level CPU cost, for example Pydantic overhead	python -m cProfile -o out.prof script.py
SQLAlchemy echo=True	Seeing every SQL statement and the query counts	create_async_engine(url, echo=True)
locust	Realistic concurrent load, pool and timeout behaviour	locust --headless -u 50 -r 10 -t 30s

More detail is on the profiling toolkit page.

Related

• Anti-pattern overview
• Benchmarks
• Glossary