SQLAlchemy test hooks dispatch queued jobs before the outer commit with SQLAlchemy 2.0.51
SQLAlchemy test hooks dispatch queued jobs before the outer commit. With SQLAlchemy 2.0.51, a test harness that drains queued jobs from Session.before_commit began executing companion work before the surrounding transaction finished. Under VCR replay, an LLM request for one structured signature then consumed responses recorded for another signature at the same HTTP endpoint, producing parse failures and empty optional outputs. I initially investigated cassette drift and slow simulation work; the cassette actually recorded the intended phase order, and a small real-session regression showed queued work executing while exiting an inner transaction scope.
Session.before_commit also fires when a Session.begin_nested() SAVEPOINT is released. It is not exclusively an outer-transaction event. On SQLAlchemy 2.0.51, this standalone reproduction records [True, False], corresponding to the nested release and then the outer commit:
from sqlalchemy import create_engine, event
from sqlalchemy.orm import Session
seen = []
@event.listens_for(Session, 'before_commit')
def before_commit(session):
seen.append(session.in_nested_transaction())
with Session(create_engine('sqlite://')) as session:
with session.begin():
with session.begin_nested():
pass
assert seen == [True, False]For a test harness deliberately executing queued jobs inline at commit, defer dispatch while session.in_nested_transaction() is true. Keep the queued objects for the outer commit, and discard jobs whose savepoint rolled back:
@event.listens_for(Session, 'before_commit')
def dispatch_pending_jobs(session):
if session.in_nested_transaction():
return
pending = session.info.pop('pending_jobs', [])
live_jobs = [job for job in pending
if job in session and job not in session.deleted]
process_jobs(live_jobs)The membership filter matters: after a flushed new object is rolled back with its savepoint, it can remain in a Python pending list even though SQLAlchemy has removed it from the session. Without filtering it, the outer commit can still execute rolled-back work. Tests using a real registered failing job established both boundaries: nested commit must not execute it; outer commit must execute it; rolling its savepoint back must discard it. Both regressions failed before this correction and passed afterward.
The misleading VCR symptom was downstream. Its default matchers include method, scheme, host, port, path and query, but not request body. Two LLM phases using the same endpoint can therefore consume each other's recorded responses when transaction events reorder execution. Repair the dispatch boundary before re-recording a cassette around the unintended order. This is a correction for an existing inline test harness, not a recommendation to execute production jobs before commit.