Mise à jour avec Drush
Drush est une interface en ligne de commande et un outil de scripting pour Drupal. La mise à jour vers Drupal 8 avec Drush est une alternative à l'utilisation de l'interface utilisateur du navigateur. Utiliser Drush pour la mise à jour est très utile lors de la migration de sites complexes, car cela permet de lancer les migrations une par une et d'effectuer des retours en arrière.
Installation de Drush via Composer
Les sites Drupal 8 peuvent être construits avec Composer. Si vous utilisez drupal-composer/drupal-project comme modèle de projet Composer, Drush est déjà inclus en tant que dépendance dans le fichier composer.json.
Si Drush n'est pas une dépendance dans votre projet Composer, vous pouvez l'installer via la ligne de commande :
composer require drush/drush
Note : utilisez Drush 9 pour le moment
À cause d'un problème avec Drush 10, il est recommandé d'installer Drush 9 via Composer en spécifiant drush/drush:^9.0, ce qui installe la version 9.7.2.
Cela vous donnera la dernière version stable de Drush compatible avec la dernière version de Drupal. Consultez la matrice de compatibilité Drush/Drupal pour plus d'informations.
Pour vérifier votre version de Drush, utilisez :
drush --version
Modules Drupal requis
Pour la migration avec Drush, vous devez télécharger et activer les modules additionnels suivants :
- Migrate Upgrade : fournit le support Drush pour la mise à jour de Drupal 6 ou 7 vers Drupal 8.
- Migrate Plus : ajoute des extensions aux fonctionnalités de base du mécanisme de migration.
- Migrate Tools : fournit des commandes Drush utilisées plus tard dans cette page.
IMPORTANT ! Faites très attention à choisir la bonne version pour chacun de ces trois modules. Consultez la page du projet pour sélectionner une version compatible avec votre version de noyau Drupal 8.
Pour plus d'informations sur les différents modules de mise à jour, consultez la liste des modules de mise à jour.
Définir la base de données source
Voici un exemple pour définir les détails de connexion à la base de données de votre site Drupal 6/7 source. Si votre site source utilise un préfixe de base de données, assurez-vous de l'indiquer. Vous devrez vous connecter à la fois à la base de données locale de développement (default/par défaut) et à la base de données source (D6 ou D7). L'exemple ci-dessous montre comment faire cela avec Lando. Il inclut la base de données par défaut pour la complétude.
Note : Pour éviter des problèmes, il est important de nommer la clé de base de données de migration, voir la section sur les erreurs de champ lors de la migration d’un noyau Drupal 7.
Exemple de connexion à la base de données dans 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', ];
Exemple .lando.yml
name: mywebsite
recipe: drupal8
config:
webroot: web
# Création du service base de données Drupal 7, pensez à ajouter phpmyadmin
services:
d7db:
type: mariadb
creds:
user: drupal7db
password: drupal7db
database: drupal7db
portforward: true
Importez la base de données Drupal 7, en supposant que le fichier dump s'appelle mywebsite_db.sql.gz et se trouve dans le dossier courant :
lando db-import --host=d7db --user=drupal7db mywebsite_db.sql.gz
Inspiré de https://github.com/thinktandem/migration_boilerplate.
Génération des migrations avec migrate-upgrade
Le module additionnel Migrate Tools ajoute des commandes Drush comme drush migrate-status et drush migrate-import. La liste complète des commandes Drush liées à la migration est en bas de cette page.
Si vous lancez drush migrate-status sans rien faire d'autre, vous ne verrez aucune migration disponible à exécuter. En effet, les migrations individuelles doivent d'abord être générées à partir de votre base de données source. Comme Migrate ne sait pas quelle source utiliser, les migrations ne sont pas encore créées.
Pour générer les migrations, utilisez la commande Drush drush migrate-upgrade, fournie par le module Migrate Upgrade.
Vous souhaitez probablement générer uniquement les configurations de migration pour pouvoir les exécuter individuellement. Pour cela, utilisez le paramètre --configure-only :
drush migrate-upgrade --legacy-db-url=mysql://user:password@server/db --legacy-root=http://example.com --configure-only
où :
- 'user' est le nom d'utilisateur de la base de données source.
- 'password' est le mot de passe de l'utilisateur de la base de données source.
- 'server' est le serveur de la base de données source.
- 'db' est la base de données source.
- 'http://example.com' est la racine de votre site source. Si le site source est sur un système de fichiers local, vous pouvez utiliser le chemin racine de Drupal comme valeur pour cette option. Cette valeur sera ajoutée aux chemins des fichiers pour les trouver et les importer.
L'option --legacy-db-key vous permet d'utiliser une clé du tableau $database définie dans settings.php.
Si votre site source utilise un préfixe dans les noms des tables, vous devez l'ajouter avec l'option suivante. Par exemple, si le préfixe est « drupal_ » :
drush migrate-upgrade --legacy-db-url=mysql://user:password@server/db --legacy-db-prefix=drupal_ --legacy-root=http://example.com --configure-only
Sans l'option --configure-only, drush migrate-upgrade générera puis exécutera toutes les migrations.
Après avoir lancé migrate-upgrade avec --configure-only, exécutez migrate-status pour voir la liste des migrations disponibles :
drush migrate-status
Vous pouvez ensuite examiner et exécuter sélectivement ces migrations. Pour exécuter une migration spécifique :
drush migrate-import <nom_de_migration>
Pour exécuter toutes les migrations :
drush migrate-import --all
Exécution de migrations spécifiques avec migrate-manifest
Vous pouvez également utiliser un fichier manifest pour configurer un ensemble spécifique de migrations. Cela permet de reproduire des groupes de migrations de façon répétable. Pour cela, vous aurez aussi besoin du module Migrate Manifest. Avec Migrate Manifest, vous pouvez lister toutes les migrations disponibles via :
drush migrate-template-list # Drush 8
ou
drush migrate:template:list # Drush 9
Note : le module Migrate Manifest n'est pas encore totalement compatible avec Drush 10+.
Les migrations souhaitées sont listées dans un fichier YAML, comme dans l'exemple ci-dessous. Il suffit d'y énumérer les migrations nécessaires. Migrate Manifest vous demandera d'ajouter les migrations supplémentaires nécessaires à la résolution des dépendances. Les migrations peuvent être listées dans n'importe quel ordre, elles seront exécutées dans l'ordre correct selon leurs dépendances.
# 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
Placez ce fichier manifest dans un emplacement accessible lors de l’exécution de Drush. Il est conseillé de le versionner dans votre système de contrôle de versions pour suivre les modifications des migrations.
Assurez-vous que les modules utilisés par les migrations listées dans le manifest sont présents et activés sur le site source (par exemple, le module Field pour d6_field). Sinon, des erreurs apparaîtront lors de l’exécution des migrations.
Les migrations définies dans le fichier manifest sont exécutées via la ligne de commande comme suit. Remplacez l’URL de la base de données et le chemin du fichier manifest par vos valeurs (migrate-upgrade, migrate-manifest acceptent une URL MySQL ou une clé du tableau settings.php) :
drush migrate-manifest --legacy-db-url=mysql://d6user:d6pass@localhost/drupal_6 manifest.yml
Notes pour les utilisateurs Acquia Dev Desktop
Si vous utilisez Acquia Dev Desktop avec un site Drupal 6, les identifiants par défaut sont drupaluser sans mot de passe et le port 33067 sur l’adresse IP 127.0.0.1. Cela donne une URL de connexion --legacy-db-url=mysql://drupaluser:@127.0.0.1:33067/drupal_6 dans les commandes. Exécutez drush status pour vérifier ces valeurs en cas de problème de connexion.
Référence des commandes de migration Drush
migrate-upgrade (sans alias)
Fournie par le projet Migrate Upgrade. Utilisez cette commande pour migrer Drupal 6/7 vers Drupal 8. Elle génère des configurations de migration basées sur la configuration et le contenu du site source.
Voir les exemples précédents dans cette documentation.
Exemple principal :
drush migrate-upgrade --legacy-db-key=migrate
Options :
- legacy-db-url : informations de connexion à la base source.
- legacy-db-prefix : préfixe des tables dans la base source.
- legacy-root : chemin vers le site source, utilisé pour importer les fichiers. Pour fichiers privés, utilisez un chemin local, pour fichiers publics HTTP(S) fonctionne aussi.
- --configure-only : crée uniquement les configurations de migration sans les exécuter.
migrate-status (ms)
Fournie par le module Migrate Tools. Liste toutes les migrations avec leur statut actuel.
Exemple :
drush migrate-status
migrate-import (mi)
Fournie par Migrate Tools. Exécute une ou plusieurs migrations. Utilisée pour les migrations personnalisées ou importées. Par exemple, pour lancer une migration personnalisée :
Exemples :
drush migrate-import migration_id drush migrate-import --group=files
Options :
- all : exécute toutes les migrations configurées.
- group : exécute toutes les migrations d’un groupe donné.
- limit : limite le nombre d’éléments traités par migration.
- feedback : fréquence des messages d’avancement.
- idlist : liste CSV des identifiants source à importer.
- update : importe aussi les éléments déjà importés mais modifiés.
- force : force l’exécution même si des dépendances ne sont pas satisfaites.
Cas d’usage :
- Après migrate-upgrade --configure-only, les objets de configuration sont créés, mais la migration ne peut pas être exécutée directement. Utilisez migrate-import pour exécuter la migration.
- Pour les migrations personnalisées importées, utilisez migrate-import pour les lancer.
Astuce : si vous importez une configuration de migration personnalisée et devez la mettre à jour, utilisez le module Configuration Update Manager.
migrate-rollback (mr)
Fournie par Migrate Tools. Permet de revenir en arrière sur une migration. Utile pour les tests ou recommencer après un problème. Utilisez avec l’identifiant ou le groupe de migration.
Exemples :
drush migrate-rollback migration_id drush migrate-rollback --group=files
migrate-stop (mst)
Fournie par Migrate Tools. Arrête une migration en cours.
Exemple :
drush migrate-stop migration_id
migrate-reset-status (mrs)
Fournie par Migrate Tools. Réinitialise le statut d’une migration active à « en attente ».
Exemple :
drush migrate-reset-status migration_id
migrate-messages (mmsg)
Fournie par Migrate Tools. Affiche les messages liés à une migration, utile en cas d’échec pour diagnostiquer.
Exemple :
drush migrate-messages migration_id
migrate-fields-source (mfs)
Fournie par Migrate Tools. Liste les champs disponibles dans la source pour le mapping.
Exemple :
drush migrate-fields-source migration_id