ASE/BUGFIX_pool_pre_ping.md

# Bug Fix: pool_pre_ping Parameter Error

**Data**: 2025-10-11
**Severity**: HIGH (blocca l'avvio)
**Status**: ✅ RISOLTO

## 🐛 Problema

Durante il testing del graceful shutdown, l'applicazione falliva all'avvio con errore:

```
run_orchestrator.ERROR: Errore principale: connect() got an unexpected keyword argument 'pool_pre_ping'
```

## 🔍 Causa Root

Il parametro `pool_pre_ping=True` era stato aggiunto alla configurazione del pool `aiomysql`, ma questo parametro **non è supportato** da `aiomysql`.

Questo parametro esiste in **SQLAlchemy** per verificare le connessioni prima dell'uso, ma `aiomysql` usa un meccanismo diverso.

## ✅ Soluzione

### File: `src/utils/orchestrator_utils.py`

**PRIMA** (non funzionante):
```python
pool = await aiomysql.create_pool(
    host=cfg.dbhost,
    user=cfg.dbuser,
    password=cfg.dbpass,
    db=cfg.dbname,
    minsize=cfg.max_threads,
    maxsize=cfg.max_threads * 4,
    pool_recycle=3600,
    pool_pre_ping=True,  # ❌ ERRORE: non supportato da aiomysql
)
```

**DOPO** (corretto):
```python
pool = await aiomysql.create_pool(
    host=cfg.dbhost,
    user=cfg.dbuser,
    password=cfg.dbpass,
    db=cfg.dbname,
    minsize=cfg.max_threads,
    maxsize=cfg.max_threads * 4,
    pool_recycle=3600,
    # Note: aiomysql doesn't support pool_pre_ping like SQLAlchemy
    # Connection validity is checked via pool_recycle
)
```

## 📝 Parametri aiomysql.create_pool Supportati

Ecco i parametri corretti per `aiomysql.create_pool`:

| Parametro | Tipo | Default | Descrizione |
|-----------|------|---------|-------------|
| `host` | str | 'localhost' | Hostname database |
| `port` | int | 3306 | Porta database |
| `user` | str | None | Username |
| `password` | str | None | Password |
| `db` | str | None | Nome database |
| `minsize` | int | 1 | Numero minimo connessioni nel pool |
| `maxsize` | int | 10 | Numero massimo connessioni nel pool |
| `pool_recycle` | int | -1 | Secondi prima di riciclare connessioni (-1 = mai) |
| `echo` | bool | False | Log delle query SQL |
| `charset` | str | '' | Character set |
| `connect_timeout` | int | None | Timeout connessione in secondi |
| `autocommit` | bool | False | Autocommit mode |

**Non supportati** (sono di SQLAlchemy):
- ❌ `pool_pre_ping`
- ❌ `pool_size`
- ❌ `max_overflow`

## 🔧 Come aiomysql Gestisce Connessioni Stale

`aiomysql` non ha `pool_pre_ping`, ma gestisce le connessioni stale tramite:

1. **`pool_recycle=3600`**: Ricicla automaticamente connessioni dopo 1 ora (3600 secondi)
   - Previene timeout MySQL (default: 28800 secondi / 8 ore)
   - Previene connessioni stale

2. **Exception Handling**: Se una connessione è morta, `aiomysql` la rimuove dal pool automaticamente quando si verifica un errore

3. **Lazy Connection**: Le connessioni sono create on-demand, non tutte all'avvio

## 📚 Documentazione Aggiornata

### File Aggiornati:
1. ✅ [orchestrator_utils.py](src/utils/orchestrator_utils.py) - Rimosso parametro errato
2. ✅ [GRACEFUL_SHUTDOWN.md](GRACEFUL_SHUTDOWN.md) - Corretta documentazione pool
3. ✅ [SECURITY_FIXES.md](SECURITY_FIXES.md) - Corretta checklist

## 🧪 Verifica

```bash
# Test sintassi
python3 -m py_compile src/utils/orchestrator_utils.py

# Test avvio
python src/send_orchestrator.py
# Dovrebbe avviarsi senza errori
```

## 💡 Best Practice per aiomysql

### Configurazione Raccomandata

```python
pool = await aiomysql.create_pool(
    host=cfg.dbhost,
    user=cfg.dbuser,
    password=cfg.dbpass,
    db=cfg.dbname,
    minsize=cfg.max_threads,           # 1 connessione per worker
    maxsize=cfg.max_threads * 2,       # Max 2x workers (non 4x)
    pool_recycle=3600,                 # Ricicla ogni ora
    connect_timeout=10,                # Timeout connessione 10s
    charset='utf8mb4',                 # UTF-8 completo
    autocommit=False,                  # Transazioni esplicite
)
```

### Perché maxsize = 2x invece di 4x?

- Ogni worker usa 1 connessione alla volta
- maxsize eccessivo spreca risorse
- Con 4 worker: minsize=4, maxsize=8 è più che sufficiente

## 🔗 Riferimenti

- [aiomysql Documentation](https://aiomysql.readthedocs.io/en/stable/pool.html)
- [PyMySQL Connection Arguments](https://pymysql.readthedocs.io/en/latest/modules/connections.html)
- [SQLAlchemy Engine Configuration](https://docs.sqlalchemy.org/en/14/core/engines.html) (per confronto)

---

## ✅ Checklist Risoluzione

- ✅ Rimosso `pool_pre_ping=True` da orchestrator_utils.py
- ✅ Aggiunto commento esplicativo
- ✅ Aggiornata documentazione GRACEFUL_SHUTDOWN.md
- ✅ Aggiornata documentazione SECURITY_FIXES.md
- ✅ Verificata sintassi Python
- ⚠️ Test funzionale da completare

---

**Grazie per la segnalazione del bug!** 🙏

Questo tipo di feedback durante il testing è preziosissimo per individuare problemi prima del deploy in produzione.