...
Eroare System Design · Baza de date: conexiuni, lock-uri, interogări lente

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

Pe scurt

Pool-ul SQLAlchemy (5 conexiuni + 10 suplimentare) a rămas fără conexiuni libere 30 de secunde. Cel mai des, sesiunile nu sunt închise (leak) sau o cerere ține conexiunea foarte mult. Folosește `with Session(...)` sau dependințe care închid sesiunea, apoi dimensionează pool-ul.

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

SQLAlchemy folosește implicit QueuePool cu pool_size=5 și max_overflow=10: cel mult 15 conexiuni simultane per proces. Când toate sunt luate, o cerere nouă așteaptă pool_timeout (30 de secunde), apoi aruncă TimeoutError cu acest mesaj.

În aplicațiile web (Flask, FastAPI) cauza tipică e o sesiune deschisă și neînchisă: o rută care creează Session() fără close(), o excepție care sare peste închidere, sau o sesiune globală. Fiecare cerere lasă în urmă o conexiune ocupată, iar după 15 cereri aplicația se blochează. A doua cauză e lucrul lung ținut în sesiune: apeluri externe sau procesări mari între interogări.

Atenție și la calculul total: fiecare proces Gunicorn sau Uvicorn are propriul pool, deci 8 workeri × 15 = 120 de conexiuni posibile spre bază.

De ce apare: cauzele frecvente

1Sesiune care nu se închide

Greșit
@app.get('/produse')
def produse():
    s = SessionLocal()
    return s.query(Produs).all()
Corect
def get_db():
    with SessionLocal() as s:
        yield s

@app.get('/produse')
def produse(db: Session = Depends(get_db)):
    return db.query(Produs).all()

Dependința închide sesiunea după fiecare cerere, deci conexiunea revine în pool.

2Lucru lent cu sesiunea deschisă

Greșit
with SessionLocal() as s:
    comenzi = s.query(Comanda).all()
    trimite_emailuri(comenzi)   # minute întregi
Corect
with SessionLocal() as s:
    comenzi = s.query(Comanda).all()
    s.expunge_all()
trimite_emailuri(comenzi)

Conexiunea se eliberează imediat după citire; trimiterea durează fără să blocheze pool-ul.

Repară tu

Repară eroarea, direct în pagină

Răspunde la cele trei întrebări despre QueuePool limit of size 5 overflow 10 reached.

Indiciu

Numără conexiunile pe care le poate da pool-ul și gândește-te ce se întâmplă cu una neînchisă.

Alte forme ale mesajului

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

Cum o eviți pe viitor

  • Deschide sesiunile doar cu context managers sau dependințe care le închid.
  • Ține sesiunea deschisă doar cât durează lucrul cu baza.
  • Calculează procese × (pool_size + max_overflow) față de limita bazei.
  • Folosește pool_pre_ping=True și pool_recycle pentru conexiunile tăiate de rețea.

Întrebări frecvente

De ce aplicația merge la început și se blochează după un timp?

E semnul clasic de leak: fiecare cerere pierde o conexiune, iar după ce se epuizează toate 15, orice cerere nouă așteaptă și dă timeout.

Ce face max_overflow?

Permite conexiuni temporare peste pool_size, închise când nu mai sunt folosite. E o rezervă pentru vârfuri, nu o soluție pentru leak.

Erori înrudite

← Toate erorile System Design

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Învață System Design de la zero, cu exerciții la fiecare lecție

Curs System Design: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 10 lecții sunt gratuite.