skip to content

Why does SQLAlchemy provide `scoped_session`, and what must a thread-pool worker call on it when each task finishes?

level: middleimportance: should knowfreq 45%

answer

  1. a Session is not thread-safe
  2. registry keyed by the current thread
  3. same Session on every call in a thread
  4. remove() before the thread is reused

basics

~20 s

A Session must not be shared across threads; scoped_session is a registry that gives each thread its own Session behind one global object. A pool worker calls remove() after each task to close and discard that Session.

solid answer

~50 s

A `Session` is a mutable, unsynchronised object representing one transaction on one connection per engine, so SQLAlchemy's rule is a **Session per thread**. `scoped_session(sessionmaker(engine))` is a **registry**: by default it stores Sessions in a `threading.local()`, so calling it returns the same Session every time within one thread and a different one in another, and it proxies Session methods, so `Session.add()` and `Session.commit()` act on the current thread's Session. That lets code deep in a call stack reach the Session without passing it around. `scoped_session.remove()` calls `close()` on the current Session, rolling back any open transaction and releasing its connection, then discards it so the next call builds a new one. Pool threads stay alive between tasks, so without `remove()` in a `finally` a task inherits the previous task's Session, its objects and possibly its open transaction.

code

python · 40 lines
python
from concurrent.futures import ThreadPoolExecutor

from sqlalchemy import create_engine, func, select, String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, scoped_session, sessionmaker


class Base(DeclarativeBase):
    pass


class Invoice(Base):
    __tablename__ = "invoice"
    id: Mapped[int] = mapped_column(primary_key=True)
    number: Mapped[str] = mapped_column(String(20))


engine = create_engine("sqlite:///invoices.db")
Base.metadata.drop_all(engine)
Base.metadata.create_all(engine)
Session = scoped_session(sessionmaker(engine))  # one registry, a Session per thread


def save_invoice(n: int) -> None:
    session = Session()
    assert session is Session()  # same thread, same Session
    try:
        session.add(Invoice(number=f"INV-{n}"))
        Session.commit()  # the registry proxies to this thread's Session
    except Exception:
        Session.rollback()
        raise
    finally:
        Session.remove()  # close it and clear the slot before the thread is reused


with ThreadPoolExecutor(max_workers=4) as pool:
    list(pool.map(save_invoice, range(20)))

print(Session.scalar(select(func.count(Invoice.id))))  # 20
Session.remove()

go deeper

for a junior

Recall the rule: one Session per thread, created from a shared sessionmaker, and never a single module-level Session used by every thread.

for a middle

Explain scoped_session as a thread-local registry that returns the same Session within a thread, proxies its methods, and whose remove() closes and discards it.

for a senior

Diagnose stale objects, held connections and inherited failed transactions in pooled workers that skip remove(), and fix them with a finally block or a local Session per task.

for a principal

Choose between explicit Session passing and a global scoped_session registry for a codebase, weighing plumbing cost against hidden state and the cleanup every scope must guarantee.

## Why a Session cannot be shared between threads A SQLAlchemy **`Session`** is a **mutable, stateful** object with no internal locking. It represents a single database transaction on a single connection per engine, and it moves through internal states (transaction begun, connection provisioned, savepoint in play, flush in progress) as it issues commands. Two threads calling the same Session at once interleave those transitions and the commands on its connection. SQLAlchemy proactively detects concurrent method calls on one Session and raises **`IllegalStateChangeError`** or an `InvalidRequestError` such as "This session is provisioning a new connection; concurrent operations are not permitted". Those errors are a warning system, not a lock: without them the same misuse would leave invalid state in the Session and hard-to-debug errors on the database connection itself. The supported model is **a Session per thread**: concurrent work runs as concurrent transactions. ## The simplest answer: a local Session per task The recommended pattern needs no registry at all. Each task opens its own Session from a shared `sessionmaker` in the top-level function that runs in the thread: ```python def settle(invoice_id: int) -> None: with Session() as session, session.begin(): ... ``` The `sessionmaker` and the `Engine` are safe to share; each `Session()` call returns a new, private Session whose lifetime matches the task. ## What `scoped_session` adds Some codebases cannot pass a Session down through every function. **`scoped_session`** serves them: it wraps a factory, usually a `sessionmaker`, in a **registry** that hands out one Session per scope. - **Thread-local by default.** The registry keeps Sessions in a `threading.local()`. Calling `Session()` twice in the same thread returns the **same** Session; another thread gets its own. - **Proxy methods.** The registry forwards Session methods, so `Session.add(obj)`, `Session.execute(stmt)` and `Session.commit()` act on the current thread's Session without fetching it first. - **Custom scopes.** `scoped_session(factory, scopefunc=...)` keys the registry by whatever the function returns instead of the thread. Such a registry is a plain dictionary that is never cleaned up by itself, so `remove()` must be called reliably. ## `remove()` and thread pools **`scoped_session.remove()`** does two things: 1. calls `Session.close()` on the current scope's Session, which expunges its objects, rolls back any open transaction and returns the connection to the pool; 2. discards that Session, so the next call in the same scope creates a fresh one. When a thread ends, its `threading.local()` storage is garbage collected, so short-lived threads are safe even without `remove()`. A **thread pool** is different: its threads live for the whole job and run task after task. Without `remove()`, task two in a worker thread receives task one's Session, with: - the objects task one loaded, now stale; - a transaction task one began and never ended, holding a pooled connection; - or an inactive transaction left by task one's failed flush, which makes task two fail. The fix is a `try` / `finally` in each task that ends with `Session.remove()`, as in the example, or the equivalent hook a framework provides at the end of each unit of work. ## A checklist for pooled workers 1. Build the `Engine` and the `scoped_session(sessionmaker(engine))` registry once, at import time. 2. In each task, do the work, then call `Session.commit()`, or `Session.rollback()` in an `except` branch. 3. Call `Session.remove()` in a `finally`, so a failing task still hands the next one a clean slot. 4. Keep ORM objects inside the task that loaded them; a task that needs the same row loads it through its own Session. ## Comparing the two approaches | | local `with Session()` per task | `scoped_session` | |---|---|---| | How code reaches the Session | passed as an argument | global registry, proxied calls | | Cleanup | the `with` block closes it | `remove()` must be called | | Scope | exactly the block | the thread, or a custom `scopefunc` | | Risk | parameter plumbing | leaks across pooled tasks | ## Limits `threading.local()` assumes one task per thread at a time. Application servers built on green threads or other alternative forms of concurrency break that assumption, and the default registry can then produce race conditions; the asyncio extension has its own scoped registry that needs a custom scoping function. Neither registry makes a single Session safe for concurrent use: it only makes it easy to give each thread its own.

  • What does a SQLAlchemy `scoped_session` gain from `scopefunc`, and what does it cost?
    `scoped_session(factory, scopefunc=fn)` keys the registry by `fn()` instead of the current thread, so a Session can follow any unit of work the application can identify, such as a request object. The registry is then a plain dictionary that never cleans itself up, so code must call `remove()` reliably at the end of every scope or Sessions and their connections accumulate.
  • Is it safe to call methods on a SQLAlchemy `sessionmaker` or `Engine` from many threads?
    Yes. Both are factories, documented as usable by any number of functions and threads at once, and they are normally created once at module level. The thread-safety rule applies to the `Session` objects they produce: each one belongs to one thread, or one task, at a time.

A scoped_session is a hotel front desk that keeps one key per room: whoever asks from room 12 always gets room 12's key, and remove() is checkout, so the next guest in that room is handed a fresh key rather than the last guest's.

  • A Session is thread-safe because the engine's pool hands each thread its own connection.
  • scoped_session makes one Session safe to use from many threads at once.
  • Calling a scoped_session registry returns a new Session on every call.
  • Pool threads never need remove() because thread-local storage cleans itself up.
  • scoped_session.remove() commits the current Session before discarding it.