skip to content

In FastAPI 0.143, when does a yield dependency on a long-lived @app.websocket endpoint run its teardown, and what does that cost when it holds a database session?

level: seniorimportance: should knowfreq 20%

answer

  1. resolved when the socket opens
  2. the handler's return is the only exit
  3. scope does not shorten it here
  4. resources held per open socket

basics

~20 s

A yield dependency on a WebSocket endpoint is torn down only after the handler returns, usually on disconnect, under either scope. A database session injected that way lives as long as the socket; open a short session per message instead.

solid answer

~50 s

In FastAPI 0.143 a WebSocket route wraps the whole handler call in the two exit stacks that yield dependencies register on, one for `scope="request"` and one for `scope="function"`. Dependencies are resolved once, at connect, and their teardown runs only after the handler returns, which for a chat socket is when the client leaves. `Depends(scope="function")`, which on an HTTP route releases a dependency before the response is sent, gains nothing here because the handler *is* the connection. A yield dependency that opens a database session therefore keeps that session, and any connection or transaction it has taken from the pool, for the socket's whole life; a few hundred idle chat users can drain the pool and stall unrelated HTTP endpoints. Keep connect-time dependencies cheap (authentication, settings) and open a short-lived session inside the loop for each message that needs the database.

code

python · 35 lines
python
from typing import Annotated

from fastapi import Depends, FastAPI, WebSocket, WebSocketDisconnect
from fastapi.testclient import TestClient

app = FastAPI()
events: list[str] = []


async def get_resource():
    events.append("opened")
    try:
        yield "pooled connection"
    finally:
        events.append("closed")


@app.websocket("/rooms/{room_id}/ws")
async def room_socket(
    websocket: WebSocket,
    room_id: str,
    resource: Annotated[str, Depends(get_resource, scope="function")],
):
    await websocket.accept()
    try:
        while True:
            events.append(f"message: {await websocket.receive_text()}")
    except WebSocketDisconnect:
        events.append("client left")


with TestClient(app).websocket_connect("/rooms/lobby/ws") as ws:
    ws.send_text("one")
    ws.send_text("two")
print(events)

go deeper

for a junior

Remember that a WebSocket endpoint's dependencies are set up when the socket opens and cleaned up only when the handler finishes.

for a middle

Explain that both yield scopes unwind only after the handler returns, so Depends(scope="function") brings no earlier release on a socket.

for a senior

Diagnose pool exhaustion caused by socket-held sessions and fix it with a factory from lifespan and a short session per message.

for a principal

Set the team rule that socket endpoints inject only cheap, connect-time values, and that per-message work opens and closes its own resources.

A **yield dependency** runs its code up to `yield` before the endpoint, hands the yielded value to the endpoint, and runs the code after `yield` (its teardown) later. On HTTP routes, FastAPI 0.121 added `Depends(scope=...)` to choose when that later is. On WebSocket routes the answer is simpler and more expensive. ## How FastAPI runs a WebSocket route's dependencies For each new connection, FastAPI 0.143 does the following: 1. Opens two exit stacks, the request stack and, inside it, the function stack. 2. Solves the endpoint's dependencies once, registering each yield dependency's teardown on the stack its `scope` names (`"request"` is the default for yield dependencies). 3. Awaits the handler function, which for a socket usually runs a receive loop until the client leaves. 4. When the handler returns or raises, unwinds the function stack, then the request stack, running teardowns in reverse order. Steps 3 and 4 are the point: **teardown cannot happen before the handler returns**, and the handler returns only when the conversation ends. ## Scope on WebSocket routes versus HTTP routes | Dependency scope | HTTP path operation | WebSocket endpoint | |---|---|---| | `scope="request"` (default) | teardown after the response is sent | teardown after the handler returns | | `scope="function"` | teardown after the function returns, before the response is sent | teardown after the handler returns | | non-yield dependency | nothing to tear down | nothing to tear down | On a socket both rows collapse into one: the dependency lives exactly as long as the connection. ## What a held session costs - **Pool capacity.** A session that has run a query and not ended its transaction typically keeps its connection checked out. One per idle socket adds up quickly. - **Collateral damage.** HTTP endpoints share the same pool, so they start waiting for connections while CPU sits idle. - **Long transactions.** An open transaction held for hours can block maintenance and keep old row versions alive, depending on the database. - **Stale state.** Objects loaded at connect are reused for hours instead of being read fresh per message. ## The pattern that fits sockets 1. Keep connect-time dependencies to things that are cheap to hold: the authenticated user, settings, a room identifier. 2. Create the engine or session factory once, in `lifespan`, and make it available to the handler. 3. Inside the receive loop, open a session per message in a `with` block, do the work, commit, and let it close before awaiting the next message. 4. Do not hold ORM objects across messages; keep identifiers and reload. Authentication that needs the database fits the same rule. A plain, non-yield dependency can open a session in a `with` block inside its own body, load the user, and return plain values such as the user id and roles; the session closes before the dependency returns, long before the handler starts its loop. Only the yield form ties the resource's lifetime to the handler. Pool sizing and session mechanics in general are covered with the session-per-request recipe; the WebSocket-specific fact is that the request is the whole connection. ## Why FastAPI cannot release it earlier On an HTTP route there is a natural boundary between running the function and sending the response, and `scope="function"` uses it. A WebSocket handler has no such boundary: sending and receiving happen inside the function, interleaved, for as long as the connection lasts. The only moment FastAPI knows the dependency's value is no longer needed is when the function ends. That is why the fix belongs in the handler's structure, not in a dependency parameter. The same holds for plain `def` yield dependencies: FastAPI enters and exits them in the thread pool, but the exit still waits for the handler to return. ## Diagnosing it in production - Database pool timeouts on ordinary HTTP endpoints that track the number of open sockets rather than request rate. - Checked-out pool connections hovering near the number of connected chat clients. - The problem vanishing the moment sockets close, during a deploy or a client outage, and returning as clients reconnect. ## The version angle `Depends(scope="function")` exists since FastAPI 0.121, and material written about it describes HTTP behaviour. A candidate who suggests it as the fix for socket endpoints has applied the HTTP rule where it does not help; the source wraps the whole socket handler in both stacks.

  • Where should a FastAPI WebSocket handler get its database session from, then?
    From a session factory created once in `lifespan` and handed to the handler, for example through lifespan state or a cheap dependency that returns the factory rather than a session. Inside the loop, open a session per message in a `with` block, do the work, commit, and let it close before awaiting the next message, so pool use tracks active work instead of open sockets.
  • How would you spot this problem in a running FastAPI service?
    Look for pool exhaustion that follows the number of open sockets rather than request rate: HTTP endpoints time out waiting for database connections while CPU is idle, and the pool's checked-out count sits near the number of connected chat clients. The tell is that it disappears when sockets close, such as during a deploy, and returns as clients reconnect.
  • Does the teardown still run if the WebSocket handler raises instead of returning?
    Yes. The exit stacks are `async with` blocks around the handler call, so an exception, including an uncaught `WebSocketDisconnect` or a raised `WebSocketException`, unwinds through them. The exception is thrown into the yield dependency at its `yield`, so its `except` and `finally` code runs before the error propagates.

It is like booking a meeting room for the whole day because you might need it for a five-minute call: the room is yours until you leave the building, and colleagues queue outside it all afternoon.

  • A yield dependency on a WebSocket route is torn down after each message.
  • Depends(scope="function") closes the session as soon as accept() returns.
  • An idle socket holds no database resources because no query is running.
  • Teardown is skipped when the client drops the connection abruptly.

Assumes FastAPI 0.143; Depends(scope=...) for yield dependencies exists since 0.121, and on WebSocket routes neither scope ends before the handler returns.