SQLAlchemy "OperationalError" / pool timeout (QueuePool) in CI

SQLAlchemy's connection pool handed out all its connections and a request waited past the timeout for one to free up. Either connections were leaked (sessions not closed) or the pool is too small for the concurrency.

What this error means

A run fails with "TimeoutError: QueuePool limit of size 5 overflow 10 reached, connection timed out, timeout 30.00" under concurrent DB access in CI.

sqlalchemy.exc.TimeoutError: QueuePool limit of size 5 overflow 10 reached,
connection timed out, timeout 30.00

Common causes

Connections or sessions are not returned to the pool

Sessions opened without being closed (or committed/rolled back) hold connections, draining the pool until none are free.

Pool too small for the test concurrency

Parallel tests open more concurrent connections than pool_size + max_overflow, so requests time out waiting.

How to fix it

Always close sessions

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

with Session(engine) as session:
    session.execute(stmt)
    session.commit()

Size the pool for the concurrency

Raise pool size/overflow to match parallel workers when leaks are not the cause.

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

How to prevent it

• Scope sessions with context managers or fixtures so they always close.
• Match pool size to test parallelism.
• Use pool_pre_ping to drop dead connections cleanly.

Related guides