skip to content

A FastAPI orders export streams a large CSV through StreamingResponse; when does its SessionDep session close, and when is Depends(scope="function") the right choice?

level: seniorimportance: should knowfreq 40%

answer

  1. two scopes for yield teardown
  2. what moved in 0.118
  3. a closed Session is reusable
  4. only for sessions used before returning

basics

~20 s

By default the session closes only after the last chunk is sent, so the generator can keep querying it. Depends(scope="function") closes it when the path operation function returns, which is right only when the stream never touches the session.

solid answer

~40 s

In FastAPI 0.143 a yield dependency defaults to `scope="request"`, so `get_session` closes after the whole streamed body is sent; a generator that reads from the session works, but the session holds its pooled connection for the full download. `Depends(get_session, scope="function")` runs teardown when the path operation function returns, before the first chunk. That suits a session used only up front, such as an access check before a slow stream, because the connection returns to the pool early. It is wrong when the generator queries the session: with SQLAlchemy 2 defaults a closed `Session` is reusable, so the query quietly checks out a new connection that no teardown closes. Before 0.118 teardown always ran before the response; 0.121 added `scope`.

code

python · 48 lines
python
from collections.abc import Iterator
from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.responses import StreamingResponse
from sqlmodel import Field, Session, SQLModel, create_engine, select


class Order(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    sku: str


engine = create_engine("sqlite:///orders.db", connect_args={"check_same_thread": False})
SQLModel.metadata.create_all(engine)


def get_session():
    with Session(engine) as session:
        yield session


app = FastAPI()


@app.get("/orders/export.csv")
def export_orders(session: Annotated[Session, Depends(get_session)]):
    # Default scope: the session is closed only after the last chunk is sent.
    def rows() -> Iterator[str]:
        for order in session.exec(select(Order)):
            yield f"{order.id},{order.sku}\n"

    return StreamingResponse(rows(), media_type="text/csv")


def require_export_access(
    session: Annotated[Session, Depends(get_session, scope="function")],
) -> None:
    session.exec(select(Order).limit(1)).first()  # stand-in for a permission lookup


@app.get("/orders/summary.txt", dependencies=[Depends(require_export_access)])
def stream_summary():
    # Function scope: the session above closed before the first chunk, freeing its connection.
    def lines() -> Iterator[str]:
        yield f"connections checked out while streaming: {engine.pool.checkedout()}\n"

    return StreamingResponse(lines(), media_type="text/plain")

go deeper

for a junior

Know that a yield dependency has a scope, that the default keeps the session open until the response is fully sent, and that scope="function" closes it earlier.

for a middle

Explain the 0.118 and 0.121 changes and walk through when teardown runs relative to the first and last chunk of a StreamingResponse.

for a senior

Diagnose a slow pool leak caused by a function-scoped session reused inside a generator, and decide per endpoint which scope its session needs.

for a principal

Weigh connection hold time on long downloads against simplicity, and set guidance for when exports get their own session or move off the request path.

## Two scopes for a dependency with yield Since FastAPI 0.121, `Depends()` takes a `scope` argument that decides when the code after `yield` runs. | `scope` | Teardown runs | Session closed during a stream? | |---|---|---| | `"request"` (default for yield dependencies) | After the whole response is sent, including every chunk of a streamed body, and after background tasks | No, it stays open until the last chunk | | `"function"` | When the path operation function returns, before the response is sent | Yes, before the first chunk | For a session dependency this is the difference between "the stream may keep using the session" and "the session is gone before streaming starts". ## The history behind the default - Before **0.118**, FastAPI ran yield teardown after the path operation returned but before sending the response. A `StreamingResponse` whose generator read from the session found the session already closed. - **0.118** moved teardown back after the response, so the default now covers streamed bodies. - **0.121** added `Depends(scope="function")` for the opposite need: dependencies whose resources should be released before a long response. Older answers that say "the session is always closed before streaming" describe the pre-0.118 behaviour. ## The export that needs the default The orders export builds rows lazily from a query: ```python def export_orders(session: Annotated[Session, Depends(get_session)]): def rows(): for order in session.exec(select(Order)): yield f"{order.id},{order.sku}\n" return StreamingResponse(rows(), media_type="text/csv") ``` Under the default scope the generator runs while FastAPI is sending the body, and the session closes only after the last chunk. The cost: once the query has started, the session holds a pooled connection for the whole stream, so a slow client downloading a large export keeps one connection checked out the entire time. ## What goes wrong with scope="function" here If the same endpoint declared `Depends(get_session, scope="function")`, the `with` block in `get_session` closes the session before the first chunk. The generator then calls `session.exec(...)` on a closed session. With SQLAlchemy 2's defaults a closed `Session` can be used again, so this does not raise. Instead: 1. The query silently begins a new transaction on a newly checked-out connection. 2. FastAPI's teardown has already run, so nothing closes that session again. 3. The connection stays checked out until garbage collection reclaims the session. Each request leaks one connection for a while, which shows up later as pool timeouts with no error at the point of the bug. ## Where scope="function" is right The case FastAPI's own docs describe is a session used **only before** the response: an access check that looks the caller up, followed by a slow stream that never touches the database. - Put `scope="function"` on the session the check uses, so the connection returns to the pool before streaming starts. - Or make the stream independent: load the rows into memory first when they are few, or open a separate session inside the generator with its own `with` block. - Keep the default for any session the generator reads from. There is one rule FastAPI enforces at route registration: a yield dependency with the default request scope cannot depend on a function-scoped one, and FastAPI raises `DependencyScopeError`. A plain dependency without `yield`, such as the access check, can. ## Reviewing a streaming endpoint When a pull request adds or changes an endpoint that returns a `StreamingResponse`, four questions settle the session's scope: 1. Does the generator, or anything it calls, read from or write to the request's session? If yes, keep the default scope. 2. Is the session used only before the path operation returns, for example in an access check or to load a small result? If yes, `scope="function"` releases the connection early. 3. How long can the stream run with a slow client? A long download under the default scope holds one pooled connection per concurrent download, so a handful of exports can starve ordinary requests. 4. Does a yield dependency with the default scope take the session as a sub-dependency? Then that declaration cannot be function-scoped: FastAPI rejects it when the route is registered. Writing these answers down in the endpoint's docstring saves the next reviewer from rediscovering them. ## How to tell which one you have - Count checked-out connections while a stream is in progress: with the default scope a session that has queried holds one; with function scope it should hold none. - Watch for connections that stay checked out after requests end; that pattern points at a function-scoped session reused by a generator. - Read the endpoint, not only the dependency: the same `get_session` is right with one scope for one route and wrong for another.

  • Why can't a FastAPI yield dependency with the default scope depend on a function-scoped session dependency?
    Teardown runs in reverse order, and a request-scoped dependency may still need its sub-dependency during its own exit code, which runs after the response. A function-scoped sub-dependency would already be closed by then. FastAPI checks this when the route is registered and raises `DependencyScopeError`. The reverse is allowed: a function-scoped dependency may depend on request-scoped ones.
  • How can a streaming endpoint read from the database without holding the request's session for the whole download?
    Either load the rows before returning, when they fit in memory, and stream from the list; or open a dedicated session inside the generator with its own `with Session(engine)` block, so the generator controls exactly when it closes. Both let the request's `SessionDep` use `scope="function"` safely.

  • FastAPI always closes a yield session before a StreamingResponse starts sending.
  • scope="function" is always better because it frees connections sooner.
  • Querying a closed SQLAlchemy Session raises, so a misplaced scope fails loudly.
  • A session used only for an access check holds no connection during the stream.

Assumes FastAPI 0.143: 0.118 moved default yield teardown after the response, streamed bodies included, and 0.121 added Depends(scope="function").