sqlalchemy.exc.TimeoutError: QueuePool limit of size 5 overflow 10 reached, connection timed out, timeout 30.00
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
@app.get('/produse')
def produse():
s = SessionLocal()
return s.query(Produs).all()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ă
with SessionLocal() as s:
comenzi = s.query(Comanda).all()
trimite_emailuri(comenzi) # minute întregiwith 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ă 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ă.
Reparația
- q1: Toate cele 15 conexiuni ale pool-ului erau ocupate 30 de secunde.
- q2:
with Session(engine) as s: .... - q3: Fals.
De ce merge
Mesajul spune că pool-ul de 15 conexiuni a fost plin 30 de secunde. Dacă sesiunile nu sunt închise, orice mărime de pool se umple; reparația e închiderea sigură a sesiunilor, cu context manager.
Alte forme ale mesajului
QueuePool limit of size 10 overflow 20 reached, connection timed out, timeout 30.00TimeoutError: 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șipool_recyclepentru 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
HikariPool-1 - Connection is not available, request timed out after 30000ms. Toate conexiunile din pool-ul Hikari au fost ocupate 30 de secunde, iar cererea a renunțat. Fie pool-ul e prea mic pentru câte interogări rulează simultan, fie interogările (sau tranzacțiile) durează prea mult, fie o conexiune nu e eliberată. Calculează cu legea lui Little câte conexiuni îți trebuie și caută interogările lente. FATAL: sorry, too many clients already PostgreSQL a atins `max_connections` (implicit 100) și refuză conexiuni noi. Apare tipic după scalarea aplicației: fiecare instanță are propriul pool, iar suma lor depășește limita. Calculează instanțe × mărimea pool-ului, micșorează pool-urile și pune un pooler (PgBouncer) în față. Î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.
