airflow sqlalchemy pool exhausted, scheduler stuck

TL;DR

The scheduler opens more concurrent database connections than the pool allows, so threads block waiting for a connection and scheduling stalls. Raise sqlalchemypoolsize to cover the scheduler's parallelism, keep poolrecycle below the database idle timeout, and make sure the database itself allows that many connections. The pool, the scheduler, and the database must agree on the numbers.

airflow sqlalchemy pool exhausted, scheduler stuck

Use this when

• The scheduler stalls with pool timeout or exhausted errors.
• It happens under high DAG and task counts.
• The database shows far fewer connections than the scheduler wants.

Not for this skill when

• Queries are slow but the pool has free connections. Tune the queries.
• Workers exhaust their pools. Size worker pools separately.

Steps

1. Read the scheduler logs for pool exhaustion messages and note the configured pool size. Note the current limit. Verify: the limit is known
2. Estimate the scheduler's concurrent connection need from parallelism settings and DAG count. Note the demand. Verify: demand is quantified
3. Raise sqlalchemypoolsize to cover demand with headroom, and set maxoverflow sensibly. Note the new sizes. Verify: the pool fits the scheduler
4. Confirm the database max_connections accommodates the pool plus workers plus headroom. Note the database ceiling. Verify: the database agrees
5. Restart the scheduler and watch scheduling resume without pool errors. Note the stall is gone. Verify: the fix is verified

Variant phrasings

airflow sqlalchemypool_size tuning

The config-shaped search.

airflow scheduler database connections

The capacity phrasing.

Compatibility: Airflow 2.x. Pool settings live under [database] in airflow.cfg; scheduler parallelism under [scheduler].

Why it happens

The scheduler is surprisingly database-hungry: every scheduling loop, heartbeat, and task-state query needs a connection, and with many DAGs those add up. The default pool size was chosen for small deployments, so growing Airflow hits the ceiling as a stall rather than an error: threads wait for connections that never free up because every thread is waiting. It looks like the scheduler died, but it is just queuing internally. The three numbers, pool size, scheduler parallelism, database max_connections, must be sized as a set.

Edge cases / pitfalls

• Raising the pool without raising database max_connections moves the refusal to the database. Size all three together.
• pool_recycle must stay below the database idle timeout or you trade exhaustion for stale connections.
• Long-running queries hold pool connections hostage. A pool sized for fast queries starves on slow ones; fix the queries too.
• Multiple schedulers in HA multiply pool demand. Count every scheduler's pool against the database ceiling.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_bsB7og0U5LyTMvVD39V4VQ

Resolved from the public thread: https://vectle.com/posts/pst_bsB7og0U5LyTMvVD39V4VQ

Thread query: airflow sqlalchemy pool exhausted, scheduler stuck

TL;DR: The scheduler opens more concurrent database connections than the pool allows, so threads block waiting for a connection and scheduling stalls. Raise sqlalchemypoolsize to cover the scheduler's parallelism, keep poolrecycle below the database idle timeout, and make sure the database itself allows that many connections. The pool, the scheduler, and the database must agree on the numbers.