Aggiornamento con Drush

Drush è una shell a riga di comando e un’interfaccia di scripting per Drupal. L’aggiornamento a Drupal 8 tramite Drush è un’alternativa all’uso dell’interfaccia del browser. L’aggiornamento a Drupal 8 tramite Drush è molto utile durante la migrazione di siti complessi, perché consente di eseguire le migrazioni una per una e permette di fare rollback.

Installazione di Drush con Composer

I siti Drupal 8 possono essere costruiti con Composer. Se scegli di usare drupal-composer/drupal-project come modello di progetto Composer, avrai già Drush incluso, poiché è elencato come dipendenza nel file composer.json del progetto.

Se nel tuo progetto Composer Drush non è elencato come dipendenza, puoi installarlo dalla riga di comando con:

composer require drush/drush

Nota: usa Drush 9 al momento

A causa di un problema con Drush 10, si consiglia di installare Drush 9 con composer richiedendo drush/drush:^9.0, che installa la versione 9.7.2.

Questo ti darà l’ultima versione stabile di Drush, compatibile con l’ultima versione di Drupal. Maggiori dettagli nella matrice di compatibilità tra versioni di Drush e Drupal.

Per controllare la tua versione di Drush:

drush --version

Moduli Drupal obbligatori

Per migrare con Drush devi scaricare e abilitare i seguenti moduli contrib:

• Migrate Upgrade: fornisce il supporto Drush per l’aggiornamento da Drupal 6 o 7 a Drupal 8.
• Migrate Plus: aggiunge estensioni alle funzionalità di base del motore di migrazione.
• Migrate Tools: fornisce i comandi Drush utilizzati più avanti in questa pagina.

IMPORTANTE! Presta particolare attenzione alla scelta della versione corretta per ciascuno dei tre moduli. Consulta la pagina del progetto per selezionare la versione compatibile con la tua versione di Drupal 8 core.

Per maggiori dettagli sui diversi moduli di aggiornamento, consulta l’elenco dei moduli di aggiornamento.

Definire il database sorgente

Ecco un esempio di come definire i dettagli di connessione al database del tuo sito Drupal 6/7. Se il tuo sito sorgente utilizza un prefisso per il database, assicurati di specificarlo. Devi collegarti sia al database di sviluppo locale (default) sia al database sorgente (D6 o D7). Qui sotto è mostrato un esempio con Lando. L’esempio include anche un database di default configurato per completezza.

Nota: per evitare problemi, è importante nominare la chiave del database di migrazione “migrate”. Vedi “Field failure per Drupal 7 core” durante la migrazione.

Esempio di connessione al database in settings.php

$databases['default']['default'] = [
  'database' => 'drupal8',
  'username' => 'drupal8',
  'password' => 'drupal8',
  'prefix' => '',
  'host' => 'database',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
];

$databases['migrate']['default'] = [
  'database' => 'drupal7db',
  'username' => 'drupal7db',
  'password' => 'drupal7db',
  'prefix' => '',
  'host' => 'd7db',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
];

Esempio .lando.yml

name: mywebsite
recipe: drupal8
config:
  webroot: web

# Crea un servizio database per Drupal 7, considera di aggiungere phpmyadmin
services:
  d7db:
    type: mariadb
    creds:
      user: drupal7db
      password: drupal7db
      database: drupal7db
    portforward: true

Importa il database di Drupal 7, supponendo che il file dump si chiami mywebsite_db.sql.gz e si trovi nella cartella corrente:

lando db-import --host=d7db --user=drupal7db mywebsite_db.sql.gz

Ispirato da https://github.com/thinktandem/migration_boilerplate

Generazione delle migrazioni con migrate-upgrade

Il modulo Migrate Tools aggiunge comandi Drush come drush migrate-status e drush migrate-import. L’elenco completo dei comandi Drush legati alla migrazione è riportato in fondo a questa pagina.

Se esegui drush migrate-status senza altre azioni, non vedrai alcuna migrazione disponibile. Questo perché le singole migrazioni devono prima essere generate dal database di origine. Poiché Migrate non sa quale sorgente usare, le migrazioni non sono ancora create.

Per generare le migrazioni usa il comando Drush drush migrate-upgrade, fornito dal modulo Migrate Upgrade.

Probabilmente vorrai generare solo singole migrazioni, così da eseguirle una per una. In questo caso utilizza l’opzione --configure-only

drush migrate-upgrade --legacy-db-url=mysql://user:password@server/db --legacy-root=http://example.com --configure-only

dove:

• 'user' è l’utente del database sorgente
• 'password' è la password del database sorgente
• 'server' è il server del database sorgente
• 'db' è il database sorgente
• 'http://example.com' è la root del sito sorgente. Se il sito si trova sul filesystem locale, puoi usare il percorso della root di Drupal. Il valore che specifichi qui sarà aggiunto ai percorsi dei file per trovarli e importarli.

L’opzione --legacy-db-key ti permette di usare un array $databases con la chiave definita in settings.php.

Se il tuo sito sorgente usa un prefisso per le tabelle del database, aggiungilo come parametro extra. In questo esempio il prefisso è “drupal_”:

drush migrate-upgrade --legacy-db-url=mysql://user:password@server/db --legacy-db-prefix=drupal_ --legacy-root=http://example.com --configure-only

Se non usi l’opzione --configure-only, drush migrate-upgrade genererà ed eseguirà tutte le migrazioni.

Dopo aver eseguito migrate-upgrade con l’opzione --configure-only, esegui migrate-status per vedere l’elenco delle migrazioni disponibili:

drush migrate-status

Puoi quindi rivedere ed eseguire selettivamente queste migrazioni. Per eseguirne una singola:

drush migrate-import <migration name>

Per eseguire tutte le migrazioni in elenco:

drush migrate-import --all

Eseguire migrazioni specifiche con migrate-manifest

È anche possibile usare un file manifest per configurare un set specifico di migrazioni. Questo consente di riprodurre gruppi di migrazioni in modo coerente. Per questo metodo serve anche il modulo Migrate Manifest. Con Migrate Manifest puoi ottenere l’elenco delle migrazioni disponibili con:

drush migrate-template-list # Drush 8

oppure

drush migrate:template:list # Drush 9

Nota: attualmente Migrate Manifest non è pienamente compatibile con Drush 10+.

Le migrazioni desiderate sono definite in un file YAML, come mostrato nell’esempio seguente. Devi elencare solo le migrazioni che ti servono. Migrate Manifest ti chiederà di aggiungere ulteriori migrazioni necessarie per risolvere le dipendenze. Le migrazioni possono essere elencate in qualsiasi ordine, saranno eseguite nell’ordine corretto in base alle dipendenze.

# user 
- d6_user 
- d6_user_profile_field 
- d6_user_profile_field_instance 
- d6_user_profile_entity_display 
- d6_user_profile_entity_form_display 
- d6_profile_values:user 
- d6_filter_format 
- d6_user_role 
- d6_user_picture_entity_display 
- d6_user_picture_entity_form_display 
- d6_user_picture_file 
- d6_user_picture_field 
- d6_user_picture_field_instance 

# taxonomy 
- d6_taxonomy_vocabulary 
- d6_taxonomy_settings 
- d6_taxonomy_term 

# nodes 
- d6_node 
- d6_node_revision 
- d6_node_type 
- d6_view_modes 
- d6_filter_format 
- d6_field_instance_per_form_display 
- d6_field_instance_widget_settings 
- d6_field_formatter_settings 
- d6_field_instance 
- d6_field 
- d6_field_settings 
- d6_node_settings 
- d6_cck_field_values:* 
- d6_cck_field_revision:* 

# taxonomy fields 
- d6_term_node_revision 
- d6_term_node 
- d6_vocabulary_entity_display 
- d6_vocabulary_entity_form_display 
- d6_vocabulary_field_instance 
- d6_vocabulary_field 

# blocks 
- d6_block 
- d6_menu 

# custom blocks 
- d6_custom_block 
- d6_filter_format 

# book 
- d6_book 
- d6_book_settings 

# file migrations are configurable, see https://www.drupal.org/node/2257723 
- d6_file: 
    source: 
      conf_path: sites/assets 
    destination: 
      source_base_path: destination/base/path 
      destination_path_property: uri 

Metti il file manifest in un percorso accessibile a Drush. È consigliato salvarlo nel tuo sistema di versionamento, così puoi tracciare i cambiamenti alle tue migrazioni.

Assicurati che i moduli usati dalle migrazioni elencate nel file manifest esistano ed siano abilitati nel sito di origine (per esempio il modulo field per d6_field). Altrimenti le migrazioni produrranno errori.

Le migrazioni definite nel file manifest vengono eseguite dalla riga di comando, come segue. Sostituisci l’URL del database e il percorso al file manifest con i valori corretti (migrate-upgrade, migrate-manifest accetta URL MySQL o chiavi da settings.php):

drush migrate-manifest --legacy-db-url=mysql://d6user:d6pass@localhost/drupal_6 manifest.yml 

Note per utenti Acquia Dev Desktop

Se usi Acquia Dev Desktop e hai un sito Drupal 6 in Dev Desktop, le credenziali di default per il database sono drupaluser con password vuota e porta 33067 per il database su IP 127.0.0.1. Tutto ciò significa che nei comandi devi usare --legacy-db-url=mysql://drupaluser:@127.0.0.1:33067/drupal_6 (presupponendo che il database si chiami drupal_6). Se hai problemi di connessione, esegui drush status per controllare i valori.

Riferimento ai comandi di migrazione Drush

migrate-upgrade (nessun alias)

Fornito dal progetto Migrate Upgrade. Usalo per avviare l’aggiornamento da Drupal 6/7 a Drupal 8. Questo comando genera le configurazioni di migrazione in base alla configurazione e ai contenuti del sito di origine.

Vedi esempi riportati in precedenza in questa pagina.

Esempio base

drush migrate-upgrade --legacy-db-key=migrate

Opzioni

• legacy-db-url: informazioni di connessione al database di origine
• legacy-db-prefix: prefisso delle tabelle del database di origine
• legacy-root: percorso al sito di origine, usato per copiare i contenuti dalla directory dei file. Per i file privati deve essere un percorso locale, per i file pubblici funzionano anche http(s).
• configure-only: usalo per generare solo le configurazioni di migrazione. Quando è impostata, le migrazioni vengono create così da poterle eseguire individualmente con “drush migrate-import”.

migrate-status (ms)

Fornito dal modulo Migrate Tools. Usalo per ottenere la lista di tutte le migrazioni con lo stato corrente.

Esempio base

drush migrate-status

migrate-import (mi)

Fornito dal modulo Migrate Tools. Usalo per eseguire una o più migrazioni. È comunemente usato con migrazioni personalizzate da sorgenti non-Drupal. Per esempio, se hai creato e importato una configurazione di migrazione personalizzata, questo comando la esegue.

Esempi base

drush migrate-import migration_id
drush migrate-import --group=files

Opzioni

• all: esegue tutte le migrazioni configurate
• group: esegue tutte le migrazioni appartenenti a un gruppo
• limit: limita il numero di elementi processati per migrazione
• feedback: frequenza dei messaggi di avanzamento, in numero di elementi processati
• idlist: lista separata da virgole di ID sorgente da importare
• update: importa nuovi elementi e aggiorna quelli già migrati se sono cambiati nella sorgente
• force: forza l’operazione anche se non tutte le dipendenze sono soddisfatte

Casi d’uso comuni

• Quando usi migrate-upgrade --configure-only, vengono create configurazioni di migrazione. Poiché Drupal 8 non consente di sovrascrivere configurazioni esistenti, migrate-upgrade non può eseguire le migrazioni in quel caso. Usa invece migrate-import.
• Quando crei e importi una migrazione personalizzata (tramite interfaccia di configurazione o drush config-import), usa migrate-import per avviarla.

Tip da professionisti: se hai importato una configurazione di migrazione personalizzata e devi aggiornarla e reimportarla, usa il modulo Configuration Update Manager.

migrate-rollback (mr)

Fornito dal modulo Migrate Tools. Usalo per annullare una migrazione. È spesso utilizzato per test o se ci sono stati problemi e devi ricominciare. Usalo con l’ID o il gruppo della migrazione.

Esempi base

drush migrate-rollback migration_id
drush migrate-rollback --group=files

migrate-stop (mst)

Fornito dal modulo Migrate Tools. Usalo per fermare un’operazione di migrazione in corso.

Esempio base

drush migrate-stop migration_id

migrate-reset-status (mrs)

Fornito dal modulo Migrate Tools. Usalo per resettare lo stato di una migrazione attiva riportandolo in attesa.

Esempio base

drush migrate-reset-status migration_id

migrate-messages (mmsg)

Fornito dal modulo Migrate Tools. Usalo per visualizzare eventuali messaggi associati a una migrazione. È utile quando ci sono errori, perché mostra perché e cosa li ha causati.

Esempio base

drush migrate-messages migration_id

migrate-fields-source (mfs)

Fornito dal modulo Migrate Tools. Usalo per elencare i campi disponibili nella sorgente per il mapping.

Esempio base

drush migrate-fields-source migration_id