La gestione delle modifiche allo schema del database in tutti gli ambienti WordPress è spesso un’attività che comporta errori e perdite di tempo. Una singola query SQL sbagliata o una modifica al database dimenticata può causare l’interruzione del sito durante la distribuzione. Inoltre, azioni come gli script SQL manuali e le modifiche dirette mancano di controllo della versione, di audit trail e di coordinamento tra gli ambienti.
L’utilizzo di Radicle di Roots (in particolare di Acorn) è una soluzione che porta le migrazioni di Laravel in WordPress. Le modifiche al database, controllate in versione, vengono distribuite insieme al codice, viene monitorata automaticamente l’esecuzione delle modifiche e si ha la possibilità di ripristinare le modifiche allo schema quando necessario.
Combinando tutto questo con l’infrastruttura e gli strumenti di Kinsta, si ottiene un modo per automatizzare l’esecuzione delle migrazioni durante le distribuzioni.
Perché le modifiche al database di WordPress necessitano di un controllo di versione
Le modifiche manuali al database trattano le modifiche allo schema come operazioni una tantum piuttosto che come codice versionato. Ad esempio, esegui una query SQL per aggiungere una tabella personalizzata, esegui un’istruzione ALTER TABLE per aggiungere colonne o ti affidi agli hook di attivazione dei plugin per gestire gli aggiornamenti. Queste soluzioni inizialmente funzionano, ma smettono di essere efficaci quando si gestiscono più ambienti o si lavora con un team.
Spesso gli ambienti di staging iniziano a divergere da quelli locali quando ci si dimentica di documentare le modifiche più piccole (come l’aggiunta di una colonna al database locale), il che fa fallire anche le distribuzioni di produzione. Ciò comporta anche la mancanza di una traccia di controllo.
Le migrazioni di Laravel sono un buon modo per eliminare questi errori di coordinamento, poiché trattano le modifiche al database come codice in versione che vive nel repository Git. Questo viene distribuito insieme all’applicazione e viene eseguito nello stesso ordine in ogni ambiente.
Come funzionano le migrazioni di Laravel in WordPress con Acorn
Le migrazioni Laravel sono file PHP che definiscono le modifiche allo schema del database attraverso due metodi: up() applica le modifiche e down() le inverte. Ogni file di migrazione riceve un prefisso temporale che determina l’ordine di esecuzione. Acorn di Roots porta questo sistema di migrazione (e molto altro) su WordPress senza richiedere un’installazione completa di Laravel.
Il sistema di migrazione tiene traccia delle modifiche eseguite utilizzando una tabella migrations nel database di WordPress. Quando si esegue wp acorn migrate, Acorn compie alcune operazioni:
- Controlla la tabella per identificare le migrazioni in corso.
- Esegue le tabelle in ordine cronologico in base ai timestamp.
- Registra ogni migrazione andata a buon fine.
Questo monitoraggio evita che le migrazioni vengano eseguite più volte e mostra esattamente quali modifiche allo schema sono state applicate a qualsiasi ambiente.
Acorn integra il costruttore di schemi di Laravel, che fornisce una sintassi PHP fluida per creare e modificare le tabelle del database. Invece di scrivere SQL grezzo, si utilizzano metodi come $table->string('key')->unique() o $table->json('value')->nullable(). Questo approccio offre una sintassi indipendente dal database, sicurezza dei tipi e codice più leggibile rispetto alle istruzioni SQL con stringhe concatenate.
Creare ed eseguire la prima migrazione
La creazione delle migrazioni avviene tramite WP-CLI:
wp acorn make:migration create_app_settings_tableQuesto genera un nuovo file di migrazione nella directory database/migrations/ con il timestamp corrente e il nome specificato:
<?php
use IlluminateDatabaseMigrationsMigration;
use IlluminateDatabaseSchemaBlueprint;
use IlluminateSupportFacadesSchema;
return new class extends Migration
{
public function up(): void
{
Schema::create('app_settings', function (Blueprint $table) {
$table->id();
$table->string('key')->unique();
$table->json('value')->nullable();
$table->string('group')->default('general');
$table->boolean('is_public')->default(false);
$table->text('description')->nullable();
$table->timestamps();
$table->index('group');
$table->index('is_public');
});
}
public function down(): void
{
Schema::dropIfExists('app_settings');
}
};Il metodo up() crea la tabella con le colonne per la memorizzazione delle coppie chiave-valore, le impostazioni di raggruppamento e il monitoraggio delle voci create o modificate. Gli indici su group e is_public migliorano le prestazioni delle query. Il metodo down() rimuove completamente la tabella, consentendo di invertire la migrazione.
Esegui le migrazioni in sospeso con il comando wp acorn migrate. Questo comando esegue tutte le migrazioni non ancora eseguite, crea tabelle e modifica lo schema del database. Puoi verificare quali migrazioni sono state eseguite con il comando wp acorn migrate:status. L’output di stato mostra ogni file di migrazione con gli indicatori di esecuzione.
Quando hai bisogno di invertire l’ultimo lotto di migrazioni, usa il comando wp acorn migrate:rollback. Questo comando esegue il metodo down() per ogni migrazione dell’ultimo lotto per annullare le modifiche.
Verifica delle migrazioni con Database Studio
Dopo aver eseguito le migrazioni, Database Studio di Kinsta (o qualsiasi altro strumento per database) permette di verificare che le tabelle e le colonne previste esistano con la struttura corretta. Puoi accedere a Database Studio dalla dashboard di MyKinsta navigando in qualsiasi sito e cliccando sulla scheda Database:
La Console SQL inclusa permette di eseguire query di verifica per confermare che le migrazioni abbiano creato la struttura prevista.
Dopo aver creato la tabella app_settings, la query DESCRIBE app_settings; permette di controllare le colonne. Questa restituisce la struttura della tabella con i nomi delle colonne, i tipi e gli indici. Un’altra query: SELECT * FROM app_settings;, permette di controllare che la tabella accetti gli inserimenti.
Il filtro permette di esaminare record o colonne specifiche senza scrivere query SQL. Qui puoi cliccare sulle intestazioni delle colonne per ordinare, applicare filtri per restringere i risultati ed esportare i dati:
Queste opzioni di esportazione sono utili per testare le procedure di rollback.
Eseguire le migrazioni con SSH e WP-CLI su Kinsta
Kinsta include l’accesso SSH e WP-CLI in tutti i piani. Ciò significa che puoi eseguire i comandi di migrazione direttamente sui tuoi ambienti di staging e di produzione senza alcuna configurazione aggiuntiva.
Per eseguire le migrazioni su un ambiente Kinsta, devi prima connetterti ad esso utilizzando SSH. Le credenziali si trovano nella schermata delle informazioni di ogni sito di MyKinsta:
Una volta effettuata la connessione e l’autenticazione, vai alla root del documento del sito. Per i siti Radicle, questa è la directory public. Esegui quindi wp acorn migrate.
Il processo di migrazione visualizza un output che mostra quali migrazioni sono in corso e lo stato di completamento di ciascuna. Questa procedura funziona anche negli ambienti di staging e di produzione perché Acorn tiene traccia delle migrazioni in modo indipendente nel database di ciascun ambiente.
Testare le migrazioni negli ambienti di staging di Kinsta
Gli ambienti di staging di Kinsta sono uno spazio sicuro per testare le migrazioni prima di distribuirle in produzione, ma è necessario un flusso di lavoro affidabile per poterle testare. Una volta verificate le modifiche alla migrazione all’interno di Database Studio, prova il rollback per assicurarti che il metodo down() funzioni correttamente.
Per farlo, passa all’ambiente di staging in MyKinsta, naviga nella scheda Database e ispeziona le tabelle create o modificate dalle migrazioni.
Se scopri dei problemi durante i test di staging, il comando wp acorn migrate:rollback ti permette di ripristinare l’ultimo lotto di migrazioni e di apportare le correzioni senza influire sulla produzione. Potrai quindi modificare i file di migrazione, eseguire il commit delle modifiche, distribuire nuovamente in staging e ripetere i test.
Il push selettivo di Kinsta permette di distribuire solo le modifiche che hai testato, quindi puoi scegliere se distribuire solo i file alla produzione o se distribuire sia i file che il database:
Per i flussi di lavoro di migrazione, in genere si effettua il push solo dei file perché le migrazioni vengono eseguite sul database di produzione esistente anziché sovrascriverlo con i dati di staging.
Flusso di lavoro di distribuzione con migrazioni automatiche
I flussi di lavoro di migrazione automatizzati eseguono le modifiche allo schema del database durante la distribuzione del codice, eliminando i passaggi manuali e riducendo gli errori di distribuzione. Per ottenere questo risultato è necessario aggiungere comandi di migrazione al processo di distribuzione, sia che si tratti di script SSH manuali, di automazione delle GitHub Actions o di strumenti come Trellis di Roots.
Per le distribuzioni manuali tramite SSH, connettiti al tuo ambiente di produzione e naviga nella root del documento. Quindi, esegui questi comandi in sequenza:
git pull origin main
composer install --no-dev
npm install && npm run build
wp acorn optimize
wp acorn migrate --forceIl flag --force indica ad Acorn di eseguire le migrazioni senza richieste di conferma, il che è essenziale per le distribuzioni automatizzate in cui non puoi interagire con il terminale. L’esecuzione di questo comando dopo wp acorn optimize assicura che la cache dell’applicazione sia vuota prima dell’esecuzione delle migrazioni.
Se utilizzi GitHub Actions per la distribuzione continua, automatizzi le migrazioni nel tuo file di flusso di lavoro. Radicle include una configurazione di .github/workflows/deploy.yml che puoi modificare per includere una fase di migrazione dopo il processo di compilazione:
- name: Run migrations
run: |
ssh user@host -p port 'cd /path/to/site && wp acorn migrate --force'Il flusso di lavoro di distribuzione si collega via SSH, naviga nella directory del sito ed esegue il comando di migrazione.
Per le distribuzioni che utilizzano Trellis, le migrazioni si integrano negli hook di distribuzione. Puoi includere i seguenti elementi modificando deploy-hooks/finalize-after.yml:
- name: Run Acorn migrations
command: wp acorn migrate --force
args:
chdir: "{{ deploy_helper.new_release_path }}"Questo esegue le migrazioni dopo che Trellis ha completato le altre attività di distribuzione. Le migrazioni vengono eseguite nella nuova directory di rilascio e Trellis gestisce il rollback se la distribuzione fallisce.
Controllo della versione dei file di migrazione con Git
I file di migrazione si trovano nella directory database/migrations/ all’interno della struttura del progetto Radicle. Questa directory fa parte del repo Git, il che significa che le migrazioni viaggiano con il tuo codice attraverso il controllo di versione. Il flusso di lavoro rispecchia lo sviluppo standard: crea le migrazioni localmente, esegui il commit in un branch di funzionalità e unisci al branch principale dopo il test.
Il flusso di commit per le migrazioni segue uno schema coerente:
git add database/migrations/2025_01_03_140000_create_app_settings_table.php
git commit -m "Add app_settings table migration"
git push origin feature-branchUna volta revisionata la migrazione, esegui il merge del branch delle funzionalità a main. Questo rende la migrazione disponibile per le distribuzioni di staging e di produzione.
Il comando wp acorn migrate:status verifica che in tutti gli ambienti siano applicate le stesse migrazioni. Il comando viene eseguito su tutti gli ambienti per verificare che siano sincronizzati. Se un ambiente mostra migrazioni in sospeso, significa che ha bisogno di una distribuzione o di una migrazione manuale per mettersi in pari.
Strategie di rollback e backup del database
Tuttavia, non tutte le migrazioni sono completamente reversibili. Mentre puoi semplicemente eliminare una tabella per annullarne la creazione, una migrazione che cancella i dati è un’azione permanente. A volte, down() spiega perché non è possibile effettuare un rollback:
public function down(): void
{
// This migration cannot be reversed as we're deleting data
Log::warning("Migration cannot be reversed - data permanently deleted");
}È bene documentare queste limitazioni. I backup automatici di Kinsta forniscono una rete di sicurezza, quindi è anche importante creare un backup manuale prima di eseguire una migrazione che potrebbe causare problemi:
Vai sul tuo sito, clicca su Backup e genera un backup con un nome descrittivo. Se una migrazione causa problemi imprevisti nella produzione, puoi ripristinare il backup da questo backup attraverso MyKinsta.
Per i rollback delle migrazioni, ripristina solo il database nell’ambiente di produzione. Il ripristino viene completato in pochi minuti e riporta il database all’esatto stato catturato nel backup.
Creare flussi di lavoro affidabili per WordPress
Le migrazioni Laravel attraverso l’implementazione di Acorn di Radicle trasformano ciò che spesso è fonte di ansia in un processo prevedibile e controllato dalla versione. La combinazione di migrazioni come codice, ambienti di staging di Kinsta e Database Studio per la verifica crea un flusso di lavoro che consente di individuare i problemi di schema prima che raggiungano la produzione.
Pertanto, uno sviluppo moderno di WordPress che include strumenti come Radicle e Acorn permette di non dover scegliere tra l’ecosistema di WordPress e i framework di strumenti professionali. Lo stesso schema si applica alle queue di Laravel, al templating di Blade e ai comandi WP-CLI personalizzati tramite Acorn.
Se non vedi l’ora di adottare questo flusso di lavoro, il passo successivo è quello di stabilire delle convenzioni di migrazione, come ad esempio la definizione di modelli di denominazione per i file di migrazione, la documentazione del processo e la definizione dei requisiti di test prima delle fusioni principali. L’hosting gestito per WordPress di Kinsta offre strumenti integrati per gli sviluppatori (come l’accesso SSH, gli ambienti di staging e Database Studio) che supportano i moderni flussi di lavoro, comprese le migrazioni Radicle e Acorn.
