Un’importazione estesa può fallire a causa di una connessione interrotta, di un dato non valido o del limite di tempo del processo. Se tutte le modifiche dipendono da un’unica transazione, il sistema può mantenere i blocchi troppo a lungo e perdere tutto il lavoro confermato solo alla fine. Se invece ogni riga viene salvata in modo indipendente, senza un piano di ripristino, un’interruzione può lasciare dati incoerenti.
Progettare transazioni per batch nelle importazioni PHP significa scegliere unità di lavoro che possano essere confermate, registrate e ripetute in sicurezza. Non equivale a rendere atomica l’intera importazione: normalmente, ogni batch è atomico singolarmente, mentre il processo completo può essere applicato solo in parte. Questa distinzione deve riflettersi sia nell’implementazione sia nell’esperienza operativa.
Perché un’unica transazione può essere inadeguata
Una transazione lunga può trattenere i blocchi, aumentare la pressione sul registro delle transazioni e competere con le query dell’applicazione. Se l’importazione elabora milioni di righe, è anche difficile capire quanto manca e cosa fare dopo un errore. Il comportamento esatto dipende dal motore di database, dal livello di isolamento e dal volume di scritture, quindi è opportuno misurarlo nell’ambiente reale.
Confermare ogni riga riduce la durata di ciascuna transazione, ma può moltiplicare il costo delle conferme e lasciare dipendenze tra righe applicate solo in parte. Il batch offre una via intermedia: se un’operazione del gruppo fallisce e l’eccezione si propaga, quel gruppo viene annullato; i batch precedenti, già confermati, restano. L’applicazione deve comunicarlo come avanzamento parziale, non come successo globale né come rollback totale.
Scegliere il limite transazionale adeguato
L’unità non deve essere sempre un numero fisso di righe. Deve rappresentare modifiche che possano essere convalidate e salvate in modo coerente. Se ogni record è indipendente, può bastare un batch di righe. Se più record formano un’entità di business — per esempio una testata e le relative righe — mantenerli nella stessa transazione evita di salvare un’entità incompleta.
Per scegliere la dimensione, valuta la durata di ogni batch, il volume di memoria, la contesa sulle tabelle condivise, la frequenza degli errori e il costo di ripetere il lavoro. Un batch grande riduce il numero di conferme, ma richiede più tempo per essere elaborato e aumenta il lavoro da rifare in caso di errore. Un batch piccolo limita questo costo, ma aumenta i costi aggiuntivi e può penalizzare le prestazioni. Non esiste una dimensione universale: inizia con un valore configurabile e adattalo con test di carico rappresentativi.
In PHP, evita di caricare in memoria l’intero file se puoi scorrerlo progressivamente. Leggi un gruppo limitato di righe, convalidane i campi, avvia la transazione, applica le scritture e conferma. Se si verifica un errore, annulla la transazione del batch e classifica l’errore. Con PDO, per esempio, il controllo può essere espresso con beginTransaction(), commit() e rollBack(); la gestione delle eccezioni deve garantire che non si tenti di confermare una transazione non riuscita.
Registrare l’avanzamento per riprendere in modo affidabile
Un checkpoint indica quale parte della sorgente è stata elaborata e confermata. Può essere un identificatore stabile, una posizione in un file o una chiave composta, purché permetta di riprendere senza dipendere da un ordinamento variabile. In una query paginata, di solito è più sicuro avanzare usando una chiave stabile anziché un offset che può cambiare se durante il processo vengono inseriti o eliminati record.
L’avanzamento e le modifiche del batch devono essere coordinati. Quando è possibile, salva nella stessa transazione le scritture di business e il nuovo checkpoint. In questo modo, se il processo si interrompe prima della conferma, non viene registrato un avanzamento che il database non ha applicato; se la transazione viene confermata, avanza anche il cursore. Se lo stato di esecuzione risiede in un altro sistema, questa atomicità non è automatica: occorre progettare una riconciliazione oppure accettare che i batch vengano ripetuti e renderli idempotenti.
Salva anche l’identificativo dell’importazione, il relativo stato, il checkpoint, i contatori e, se opportuno, un riferimento alla versione o all’impronta del file. Quando riprendi il processo, verifica che si tratti degli stessi dati in ingresso e di un’esecuzione recuperabile. Definisci stati espliciti, come in attesa, in corso, completata e non riuscita, e una politica per rilevare le esecuzioni abbandonate. Evita di contrassegnare un’importazione come completata solo perché il processo è terminato senza generare un’eccezione: verifica che abbia raggiunto la fine prevista.
Isolare gli errori e gestire i tentativi
Decidi in anticipo se un record non valido deve interrompere tutto, essere escluso o essere contrassegnato per la revisione. Per gli errori di formato prevedibili, può essere utile convalidare i dati prima di aprire la transazione e registrare il motivo insieme a un identificativo di riga. In caso di errori di persistenza, annulla il batch interessato. Continuare con i batch successivi è ragionevole solo se i relativi dati sono indipendenti e l’importazione può essere dichiarata parziale in modo chiaro.
Distingui gli errori permanenti — come un valore obbligatorio mancante — dai guasti transitori — come un’interruzione della connessione da cui è possibile riprendersi. Riprovare in caso di errore permanente spreca risorse e rende più difficile la diagnosi. Un nuovo tentativo per un errore transitorio può prevedere un numero limitato di tentativi e un’attesa crescente. Se i tentativi si esauriscono, conserva lo stato e il contesto necessari per indagare e riprendere senza nascondere la causa originale.
I nuovi tentativi possono ripetere le scritture se non vengono progettati con attenzione. Usa chiavi di business o identificativi della sorgente per riconoscere i record già importati e decidi se una ripetizione debba inserire, aggiornare, ignorare o segnalare un conflitto. I vincoli univoci nel database possono rafforzare questa decisione, ma non sostituiscono la logica di business. Evita che il checkpoint sia l’unico meccanismo contro i duplicati: può non essere aggiornato o non coprire le modifiche effettuate tramite un altro canale.
Se un batch invia anche email, pubblica messaggi o chiama un’API, la transazione del database non può annullare questi effetti esterni. Non eseguirli come se facessero parte di una transazione distribuita inesistente. Un’alternativa consiste nel registrare l’evento in sospeso in una tabella transazionale di eventi in uscita e poi elaborarlo con nuovi tentativi e identificativi idempotenti. Se l’effetto esterno non riesce, lo stato deve consentire di recuperarlo senza duplicare l’operazione né dichiarare che il batch è completamente terminato.
Verificare coerenza, avanzamento e ripristino
I test devono coprire più del solo percorso corretto. Simula errori prima di avviare una transazione, durante le scritture, subito prima della conferma e dopo la conferma ma prima di aggiornare qualsiasi stato esterno. Verifica quali dati restano, quale checkpoint viene conservato e se la ripresa produce il risultato atteso. Includi record duplicati, righe non valide, batch vuoti ed errori di persistenza.
In un test rappresentativo, misura la durata per batch, l’uso di memoria, il tasso di errori, il tempo di blocco e l’avanzamento. Verifica anche che i contatori distinguano le righe lette, accettate, rifiutate e confermate: «elaborate» può essere ambiguo se include modifiche annullate. Le metriche e i registri dovrebbero identificare l’importazione e il batch senza riportare dati sensibili non necessari per la diagnosi.
Checklist prima della produzione
- L’unità transazionale corrisponde a un’unità di business coerente.
- La dimensione del batch è configurabile ed è stata valutata con dati e carichi rappresentativi.
- Il checkpoint avanza solo quando il batch corrispondente è stato confermato.
- La strategia di ripresa usa una chiave stabile e identifica i dati sorgente.
- Gli errori permanenti e transitori seguono trattamenti distinti e osservabili.
- Le operazioni ripetute sono idempotenti o rilevano esplicitamente i conflitti.
- Gli effetti esterni vengono elaborati con una strategia indipendente e recuperabile.
- I test verificano gli errori in punti diversi, non solo l’esecuzione completa.
L’obiettivo non è impedire qualsiasi errore, ma limitarne le conseguenze e rendere esplicito lo stato risultante. Con limiti transazionali ragionati, checkpoint coerenti e tentativi sicuri, un’importazione PHP può riprendersi senza confondere l’avanzamento parziale con il completamento né applicare di nuovo modifiche già confermate.
