In a FastAPI session dependency, why commit inside the endpoint rather than after the yield, and what happens to uncommitted work when the endpoint raises?
answer
- when does code after yield run
- response already on the wire
- exception thrown back into the generator
- with block exit discards the transaction
basics
~20 sUnder FastAPI's default request scope, code after yield runs after the response is sent, so a failed commit there still leaves the client with a 200. Commit in the endpoint; if the endpoint raises, closing the session discards uncommitted work.
solid answer
~40 sIn FastAPI 0.143 a dependency with `yield` defaults to `scope="request"`: the code after `yield` runs only after the response, and any background tasks, are sent. A `session.commit()` there can raise an `IntegrityError` after the client already received its 200, so the write is lost silently. Committing in the endpoint lets the failure reach the exception handlers, and `Depends(get_session, scope="function")` moves the teardown commit before the response so it becomes a 500. When the endpoint raises, including `HTTPException`, FastAPI throws the exception into the generator at `yield`; the `with Session(engine)` block exits and closing the session discards the uncommitted transaction, then the exception reaches the handlers. An explicit `except Exception: session.rollback(); raise` is fine, but it must re-raise.
code
python · 47 linesimport tempfile
from pathlib import Path
from typing import Annotated
from fastapi import Depends, FastAPI
from fastapi.testclient import TestClient
from sqlmodel import Field, Session, SQLModel, create_engine
class Order(SQLModel, table=True):
id: int | None = Field(default=None, primary_key=True)
reference: str = Field(unique=True)
db_path = Path(tempfile.mkdtemp()) / "orders.db"
engine = create_engine(f"sqlite:///{db_path}", connect_args={"check_same_thread": False})
SQLModel.metadata.create_all(engine)
def get_session_commit_after_yield():
with Session(engine) as session:
yield session
session.commit()
LateCommit = Annotated[Session, Depends(get_session_commit_after_yield)]
EarlyCommit = Annotated[Session, Depends(get_session_commit_after_yield, scope="function")]
app = FastAPI()
@app.post("/orders/late")
def place_late(reference: str, session: LateCommit):
session.add(Order(reference=reference))
return {"placed": reference}
@app.post("/orders/early")
def place_early(reference: str, session: EarlyCommit):
session.add(Order(reference=reference))
return {"placed": reference}
client = TestClient(app, raise_server_exceptions=False)
print(client.post("/orders/late", params={"reference": "A-1"}).status_code) # 200: stored
print(client.post("/orders/late", params={"reference": "A-1"}).status_code) # 200: commit failed after sending
print(client.post("/orders/early", params={"reference": "A-1"}).status_code) # 500: commit failed before sendinggo deeper
Remember that nothing is saved until commit() is called, and that an exception in the endpoint leaves uncommitted changes unsaved.
Explain when the code after yield runs under the default scope, why a commit there cannot change the status already sent, and how scope="function" changes that.
Diagnose a lost write that returned 200 by reading teardown order, and review a rollback-and-swallow dependency that turns 404s into 500s.
Settle one commit convention for the codebase, endpoint commits or one function-scoped commit point, and make reviews enforce it.
## Where the commit can live A session dependency opens a session, the endpoint changes data through it, and something has to call `session.commit()`. FastAPI 0.143 gives three places to put that call, and they behave very differently. | Commit placed | When it runs | If the commit fails | |---|---|---| | In the endpoint | Before the endpoint returns | The exception reaches FastAPI's handlers; the client gets a 500, or the status your handler maps it to | | After `yield`, default `scope="request"` | After the response, and any background tasks, have been sent | The client already has its 200; the error appears only in the server log | | After `yield`, `Depends(get_session, scope="function")` | After the path operation function returns, before the response is sent | The client gets a 500 | The default scope is `"request"` for every dependency with `yield`, so a commit written after `yield` without further thought lands in the second row. ## Why a commit after yield fails silently by default The order of events for a successful request under the default scope is: 1. FastAPI runs `get_session` up to `yield` and injects the session. 2. The endpoint adds an order and returns `{"placed": "A-1"}`. 3. FastAPI serializes the return value and sends the 200 response. 4. Background tasks, if any, run. 5. FastAPI resumes the generator: `session.commit()` runs and raises, for example on a unique-constraint violation. By step 5 the response is gone. The client believes the order exists, the database does not have it, and the only trace is an unhandled-exception traceback in the server log. The release notes record why teardown sits here: before 0.118 it ran before the response, which closed sessions that a `StreamingResponse` was still using, and 0.118 moved it back after the response. 0.121 then added `Depends(scope="function")` for code that must run first. ## What happens when the endpoint raises When the path operation raises, say `HTTPException(status_code=404)` because a customer does not exist, after it already called `session.add(order)`: 1. FastAPI throws that exception into the generator at the `yield` line. 2. The `with Session(engine)` block exits on the exception, and closing the session discards the uncommitted transaction, so the added order is never stored. 3. The exception continues to FastAPI's exception handlers, and the client gets the 404. Because this happens before the error response is built, the rollback is in place before the client hears anything. Nothing commits implicitly either: if the endpoint returns normally without calling `commit()`, the close in teardown discards the work and the client still receives a 200. ## Writing the rollback explicitly Relying on close is enough with SQLAlchemy sessions, but many teams prefer the rollback to be visible: ```python def get_session(): with Session(engine) as session: try: yield session except Exception: session.rollback() raise ``` The `raise` is not optional. If the `except` block swallows the exception, FastAPI never builds a response for it: the client gets a 500 instead of the endpoint's 404, and the log shows FastAPI's "Response not awaited" error rather than the original exception. ## Choosing a convention - **Commit in the endpoint** when the endpoint decides what a successful write means and needs `session.refresh(order)` to return generated values such as the new `id`. - **Commit after `yield` with `scope="function"`** when the team wants one commit point for every write endpoint; the failure then becomes a 500 before the response is sent. - **Never commit after `yield` under the default scope** for writes the client relies on. - Keep `except ... raise` in the dependency if you add a rollback, so the endpoint's own status codes survive. ## Why tests may catch it when clients do not The silent failure has one place where it is loud. `fastapi.testclient.TestClient` defaults to `raise_server_exceptions=True`, so an exception raised in teardown after the response is re-raised from the test's `client.post(...)` call, and the test fails with the `IntegrityError`. A real client talking to Uvicorn gets no such signal: it reads its 200 and moves on, while the traceback lands in the server log next to an access-log line that says 200. Two practical consequences follow: - A test suite that builds its client with `raise_server_exceptions=False` to assert on 500 responses also hides this class of bug, so keep at least one test path with the default. - When production shows "the API said OK but the row is missing", look for teardown tracebacks timed just after successful responses. ## Mistakes worth catching in review - Assuming FastAPI commits when the endpoint returns normally: it has no autocommit; the session only closes. - Assuming `HTTPException` is "not an error" and the pending changes will be kept: it is an exception like any other inside the generator. - Believing `session.add()` writes immediately: it only stages the object until a flush or commit. - Moving the commit into a background task: background tasks run after the response, so the failure is just as invisible.
- Why must a session dependency that catches an exception to roll back always re-raise it?FastAPI learns about the endpoint's failure only through the exception leaving the generator. If the `except` block swallows it, no response is produced for it: the client gets a 500 instead of, say, the endpoint's 404, and the log shows FastAPI's "Response not awaited" error rather than the original exception. Write `session.rollback()` followed by a bare `raise`.
- An endpoint adds an order through SessionDep and returns normally without calling commit(). What does the client see, and what is stored?The client sees a normal 200 with the returned body, but nothing is stored. FastAPI has no autocommit: teardown only closes the session, and closing discards the open transaction. It is a common bug in new endpoints, which is why a team either commits in every write endpoint or puts one commit in a function-scoped dependency.
- A commit after yield is safe because FastAPI turns a failed commit into a 500.
- FastAPI commits the session automatically when the endpoint returns normally.
- Raising HTTPException keeps what the endpoint added, since it is not a server error.
- session.add() writes the row immediately, so a later exception cannot undo it.
- A rollback in the dependency's except block can swallow the exception safely.
Assumes FastAPI 0.143: default yield teardown has run after the response since 0.118, and Depends(scope="function") exists since 0.121.