Indice dei contenuti
Quando un’applicazione è ancora un prototipo, modificare una tabella sembra semplice: apri il database, aggiungi una colonna e continui a sviluppare. In produzione, però, quella tabella potrebbe contenere migliaia di record ed essere usata da richieste web, cron job e worker contemporaneamente. 🗄️
Le migrazioni database servono proprio a gestire questi cambiamenti in modo ripetibile, verificabile e coordinato con il codice.
Perché evitare le modifiche manuali
Una modifica fatta soltanto dal pannello di amministrazione è difficile da riprodurre in staging e da documentare. Se il codice viene distribuito su un altro ambiente, rischi di trovarti con due strutture differenti.
Versionare le migrazioni insieme al progetto permette invece di sapere quali modifiche sono state applicate, in quale ordine e con quale versione dell’applicazione.
Una tabella per tracciare le migrazioni
Anche in un’applicazione PHP monolitica è possibile usare un sistema leggero: una cartella database/migrations e una tabella che registra il nome o la versione delle migrazioni già eseguite.
Ogni file dovrebbe descrivere un cambiamento preciso: creazione di una tabella, aggiunta di un indice o introduzione di un campo. Il comando di deploy applica soltanto le migrazioni ancora mancanti, sotto un lock che impedisca esecuzioni concorrenti.
Il metodo expand-contract 🧱
Per modifiche delicate, preferisco separare il rilascio in più passaggi:
- Expand: aggiungi il nuovo campo o la nuova struttura mantenendo compatibilità con il codice esistente.
- Transizione: distribuisci il codice capace di gestire il nuovo schema; se necessario, migra gradualmente i dati.
- Contract: elimina le vecchie colonne o i vecchi comportamenti soltanto quando non sono più utilizzati.
Questo approccio evita di distribuire contemporaneamente una modifica distruttiva del database e un’applicazione che la richiede immediatamente. È particolarmente utile quando esistono worker o richieste ancora in esecuzione con la versione precedente.
Attenzione alle modifiche pesanti
Un ALTER TABLE può avere effetti molto diversi a seconda della versione di MariaDB, del motore, della dimensione della tabella e dell’operazione richiesta. Alcune modifiche sono rapide, altre possono richiedere lock o ricostruzioni costose.
Prima di intervenire su una tabella grande, verifica la modalità supportata, i tempi stimati e la possibilità di usare operazioni online. Non dare per scontato che aggiungere un indice o cambiare un tipo di dato sia sempre istantaneo.
Backup e rollback non sono sinonimi
Un backup verificato è indispensabile, ma ripristinare l’intero database potrebbe cancellare dati creati dopo il deploy. Il rollback del codice, inoltre, non annulla automaticamente una migrazione dello schema.
Per questo conviene progettare prima la compatibilità tra versioni. Le migrazioni distruttive devono essere l’ultima fase, non la prima. Quando serve ripristinare dati, occorre un piano che consideri anche le scritture avvenute nel frattempo.
Una checklist prima del rilascio ✅
- Prova la migrazione su un ambiente di staging con dati rappresentativi.
- Verifica che esista un backup recente e che il ripristino sia stato testato.
- Controlla spazio libero, durata prevista e possibili lock.
- Assicurati che cron job e worker siano compatibili con la transizione.
- Esegui le migrazioni una sola volta e registra gli esiti.
- Monitora errori applicativi, query lente e integrità dei dati dopo il deploy.
Un esempio: rinominare un campo senza interruzioni
Se un gestionale usa la colonna customer_name e vuoi passare a display_name, una rinomina diretta può rompere le istanze ancora in esecuzione. Puoi invece aggiungere display_name, aggiornare il codice per gestire entrambe le colonne, completare la migrazione dei valori e soltanto in un rilascio successivo rimuovere il campo precedente.
Non è il percorso più corto sulla carta, ma spesso è quello che riduce maggiormente il rischio operativo.
Automatizzare senza perdere controllo
Una pipeline può eseguire controlli preliminari e migrazioni durante il deploy, ma le operazioni distruttive meritano una conferma esplicita. Log chiari, identificativi di versione e procedure documentate aiutano a intervenire rapidamente se qualcosa non va.
Per approfondire i dettagli tecnici delle operazioni sullo schema, consulta la documentazione MariaDB su ALTER TABLE.
FAQ
Le migrazioni servono anche a un piccolo progetto PHP?
Sì. Anche poche tabelle beneficiano di modifiche versionate e riproducibili.
Posso eseguire sempre le migrazioni all’avvio dell’applicazione?
È rischioso: richieste concorrenti e modifiche lente possono causare problemi. Meglio un passaggio di deploy controllato.
Un backup basta per annullare un deploy?
No. Devi considerare la compatibilità del codice e le nuove scritture effettuate dopo il rilascio.