SQLAlchemy "QueuePool limit ... overflow ... timed out" in CI

SQLAlchemy could not give out a connection within pool_timeout because every pooled and overflow connection was already checked out. Under test concurrency this usually means connections or sessions are not being returned.

What this error means

Tests fail intermittently with "sqlalchemy.exc.TimeoutError: QueuePool limit of size 5 overflow 10 reached, connection timed out, timeout 30.00."

sqlalchemy.exc.TimeoutError: QueuePool limit of size 5 overflow 10 reached,
connection timed out, timeout 30.00 (Background on this error at: https://sqlalche.me/e/20/3o7r)

Common causes

Sessions or connections are not closed

A test or fixture opens a session and never closes it, so checked-out connections accumulate until the pool is exhausted.

Concurrency exceeds the pool size

Parallel test workers or async tasks demand more simultaneous connections than pool_size + max_overflow allows.

How to fix it

Always close sessions

Use a context manager or fixture teardown so every session returns its connection to the pool.

from sqlalchemy.orm import Session

with Session(engine) as session:
    session.execute(...)
    session.commit()
# connection is returned on exit

Size the pool for test concurrency

Raise pool_size/max_overflow (or use NullPool for tests) so the pool matches the number of parallel workers.

engine = create_engine(
    url, pool_size=10, max_overflow=20, pool_timeout=30
)

How to prevent it

• Scope sessions to a context manager or pytest fixture with teardown.
• Match pool size to your parallel test worker count.
• Consider NullPool for short-lived test processes.

Related guides