Aktualisierung mit Drush

Drush ist eine Kommandozeilen-Shell und Skriptschnittstelle für Drupal. Das Upgrade auf Drupal 8 mit Drush ist eine Alternative zur Nutzung der Browser-Benutzeroberfläche. Das Upgrade auf Drupal 8 mit Drush ist besonders nützlich bei der Migration komplexer Websites, da es erlaubt, Migrationen einzeln auszuführen und Rücksetzungen durchzuführen.

Installation von Drush mit Composer

Drupal 8-Websites können mit Composer aufgebaut werden. Wenn Sie sich entscheiden, drupal-composer/drupal-project als Composer-Projekt-Template zu verwenden, ist Drush bereits enthalten, da es als Abhängigkeit in der composer.json des Projekts aufgeführt ist.

Falls Drush in Ihrem Composer-Projekt nicht als Abhängigkeit angegeben ist, können Sie Drush über die Kommandozeile wie folgt installieren:

composer require drush/drush

Hinweis: Verwenden Sie jetzt Drush 9

Wegen eines Problems mit Drush 10 wird derzeit empfohlen, Drush 9 mit Composer zu installieren, indem drush/drush: ^9.0 verlangt wird, was zur Version 9.7.2 führt. 

Dies gibt Ihnen die neueste (stabile) Drush-Version, die mit der neuesten Drupal-Version kompatibel sein sollte. Mehr dazu lesen Sie in der Kompatibilitätsmatrix von Drush- und Drupal-Versionen.

Um Ihre Drush-Version zu prüfen, verwenden Sie

drush --version

Erforderliche Drupal-Module

Für die Migration mit Drush müssen Sie die folgenden Zusatzmodule herunterladen und aktivieren:

• Migrate Upgrade: bietet Drush-Unterstützung für das Upgrade von Drupal 6 oder 7 auf Drupal 8.
• Migrate Plus: stellt Erweiterungen für die Basisfunktionalität des Migrationsmechanismus bereit.
• Migrate Tools: stellt Drush-Befehle bereit, die später auf dieser Seite verwendet werden.

WICHTIG! Achten Sie besonders darauf, für jedes der drei genannten Module die korrekte Version auszuwählen. Bitte konsultieren Sie die Projektseite, um eine Version zu wählen, die mit Ihrer Drupal 8 Core-Version kompatibel ist.

Für weitere Informationen zu den verschiedenen Upgrade-Modulen siehe bitte die Liste der Upgrade-Module.

Definieren Sie die Quell-Datenbank

Hier ein Beispiel, wie man die Verbindungsdetails zur Datenbank Ihrer ursprünglichen Drupal 6/7-Website definiert. Wenn Ihre Quell-Website einen Datenbank-Präfix verwendet, müssen Sie diesen angeben. Sie müssen sowohl eine Verbindung zur lokalen Entwicklungsdatenbank (default/Standard) als auch zur Quell-Datenbank (D6 oder D7) herstellen. Nachfolgend ein Beispiel, wie dies mit Lando funktioniert. Das Beispiel beinhaltet die Standard-Datenbank zur Vollständigkeit.

Hinweis. Um Probleme zu vermeiden, ist es wichtig, den Migrations-Datenbankschlüssel korrekt zu benennen, siehe Abschnitt „Getting Field Failure for Drupal 7 Core.“ bei Migration.

Beispiel für die Datenbankverbindung 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',
];

Beispiel .lando.yml

name: mywebsite
recipe: drupal8
config:
  webroot: web

# Erstellen Sie den Drupal 7 Datenbankservice, überlegen Sie phpmyadmin hinzuzufügen
services:
  d7db:
    type: mariadb
    creds:
      user: drupal7db
      password: drupal7db
      database: drupal7db
    portforward: true

Importieren Sie die Drupal 7-Datenbank, wobei angenommen wird, dass die Dump-Datei mywebsite_db.sql.gz heißt und sich im aktuellen Verzeichnis befindet:

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

Inspiriert von https://github.com/thinktandem/migration_boilerplate.

Generierung von Migrationen mit migrate-upgrade

Das Zusatzmodul Migrate Tools fügt Drush-Befehle wie drush migrate-status und drush migrate-import hinzu. Eine vollständige Liste der migrationsbezogenen Drush-Befehle finden Sie am Ende dieser Seite.

Wenn Sie versuchen, den Befehl drush migrate-status ohne weitere Schritte auszuführen, sehen Sie keine verfügbaren Migrationen, da einzelne Migrationen zuerst basierend auf Ihrer Quell-Datenbank erstellt werden müssen. Da Migrate nicht weiß, welche Quelle zu verwenden ist, existieren noch keine Migrationen.

Zum Generieren von Migrationen benötigen Sie den Drush-Befehl drush migrate-upgrade, der vom Migrate Upgrade-Modul bereitgestellt wird.

Wahrscheinlich möchten Sie nur einzelne Migrationen generieren, um sie nacheinander auszuführen. Verwenden Sie dafür den Parameter --configure-only

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

wobei

• 'user' der Benutzername der Quell-Datenbank ist.
• 'password' das Passwort des Quell-Datenbankbenutzers ist.
• 'server' der Server der Quell-Datenbank ist.
• 'db' die Quell-Datenbank ist.
• 'http://example.com' die Basis-URL Ihrer Quell-Website ist. Wenn sich die alte Website lokal im Dateisystem befindet, können Sie stattdessen den Pfad zum Drupal-Stammverzeichnis als Wert verwenden. Der hier angegebene Wert wird zu den Pfaden der einzelnen Dateien addiert, um diese zu finden und zu importieren.

Die Option --legacy-db-key ermöglicht die Verwendung des $database-Arrays mit dem entsprechenden Schlüssel aus settings.php.

Wenn Ihre Quell-Website Tabellenpräfixe verwendet, müssen Sie diese als zusätzlichen Parameter angeben. Im folgenden Beispiel ist der Präfix „drupal_“:

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

Wenn Sie --configure-only nicht verwenden, generiert drush migrate-upgrade zuerst und führt dann alle Migrationen aus.

Nachdem Sie migrate-upgrade mit --configure-only ausgeführt haben, verwenden Sie migrate-status, um die Liste der verfügbaren Migrationen zu sehen:

drush migrate-status

Dann können Sie diese Migrationen ansehen und selektiv ausführen. Um eine einzelne Migration auszuführen, verwenden Sie:

drush migrate-import <migrationsname> 

Um alle Migrationen in der Liste auszuführen, verwenden Sie:

drush migrate-import --all 

Ausführen bestimmter Migrationen mit migrate-manifest

Es ist auch möglich, eine Manifest-Datei zu verwenden, um eine bestimmte Gruppe von Migrationen zu konfigurieren. Das ermöglicht es, Migrationsgruppen reproduzierbar auszuführen. Für diese Methode benötigen Sie ebenfalls das Modul Migrate Manifest. Mit Migrate Manifest können Sie eine vollständige Liste verfügbarer Migrationen mit folgenden Befehlen abrufen:

drush migrate-template-list # Drush 8

oder

drush migrate:template:list # Drush 9

Hinweis: Das Modul Migrate Manifest ist derzeit nicht vollständig kompatibel mit Drush 10+.

Die gewünschten Migrationen werden als YAML-Datei definiert, wie im folgenden Beispiel gezeigt. Sie listen nur die Migrationen auf, die Sie benötigen. Migrate Manifest wird Sie auffordern, weitere Migrationen hinzuzufügen, die aufgrund von Abhängigkeiten erforderlich sind. Migrationen können in beliebiger Reihenfolge aufgelistet werden, sie werden basierend auf ihren Abhängigkeiten in der richtigen Reihenfolge ausgeführt.

# 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 

Legen Sie die Manifest-Datei an einem Ort ab, der beim Ausführen von Drush zugänglich ist. Es wird empfohlen, diese in Ihrem Versionskontrollsystem zu speichern, damit Sie Änderungen an Ihren Migrationen verfolgen können.

Stellen Sie sicher, dass die in der Manifestdatei genannten Module auf der Quellseite installiert und aktiviert sind (z. B. das Feldmodul für d6_field). Andernfalls treten beim Ausführen der Migrationen Fehler auf.

Migrationen, die in der Manifestdatei definiert sind, werden über die Kommandozeile ausgeführt, wie unten gezeigt. Ersetzen Sie dabei die Datenbank-URL und den Pfad zur Manifestdatei durch passende Werte (z. B. migrate-upgrade, migrate-manifest akzeptiert MySQL-URLs oder settings.php-Array-Schlüssel):

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

Hinweise für Acquia Dev Desktop Nutzer

Wenn Sie Acquia Dev Desktop verwenden und eine Drupal 6-Seite darin haben, sind die Standard-Datenbank-Anmeldedaten drupaluser mit leerem Passwort und Port 33067 für die Datenbank auf der IP 127.0.0.1. Das bedeutet, dass in Befehlen mit --legacy-db-url=mysql://drupaluser:@127.0.0.1:33067/drupal_6 der Datenbankname drupal_6 angenommen wird. Führen Sie drush status aus, wenn Sie Verbindungsprobleme haben, um diese Werte zu prüfen.

Übersicht der Drush-Migrationsbefehle

migrate-upgrade (kein Alias)

Bereitgestellt vom Projekt Migrate Upgrade. Verwenden Sie diesen Befehl, um ein Upgrade von Drupal 6/7 auf Drupal 8 durchzuführen. Dieser Befehl generiert Migrationskonfigurationen basierend auf der Konfiguration und dem Inhalt der Quellwebsite.

Siehe Beispiele weiter oben auf dieser Dokumentationsseite.

Hauptbeispiel

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

Optionen

• legacy-db-url: Verbindungsinformationen zur Quell-Datenbank.
• legacy-db-prefix: Tabellenpräfix der Quell-Datenbank.
• legacy-root: Pfad zur Quellwebsite, wird verwendet, um Inhalte aus dem Dateiverzeichnis zu übernehmen. Wenn Dateien privat sind, sollte der lokale Pfad angegeben werden; für öffentliche Dateien funktionieren auch http(s)-URLs.
• nur Konfiguration: Erzeugt nur Migrationskonfigurationen, damit Migrationen einzeln mit "drush migrate-import" ausgeführt werden können.

migrate-status (ms)

Bereitgestellt vom Modul Migrate Tools. Zeigt eine Liste aller Migrationen mit ihrem aktuellen Status an.

Hauptbeispiel

drush migrate-status

migrate-import (mi)

Bereitgestellt vom Modul Migrate Tools. Wird verwendet, um eine oder mehrere Migrationen auszuführen. Dies wird oft für benutzerdefinierte Migrationen aus nicht-Drupal-Quellen genutzt. Wenn Sie eine benutzerdefinierte Migrationskonfiguration erstellt und importiert haben, können Sie diesen Befehl zum Starten der Migration verwenden.

Beispiele

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

Optionen

• all: alle konfigurierten Migrationen ausführen.
• group: alle Migrationen einer bestimmten Gruppe ausführen.
• limit: maximale Anzahl von Elementen, die in jeder Migration verarbeitet werden.
• feedback: Häufigkeit der Fortschrittsmeldungen in verarbeiteten Elementen.
• idlist: kommaseparierte Liste von Quell-IDs zum Import.
• update: migriert neue und aktualisierte Elemente erneut.
• force: zwingt die Ausführung auch wenn Abhängigkeiten nicht erfüllt sind.

Typische Anwendungsfälle

• Wenn migrate-upgrade --configure-only genutzt wird, werden Konfigurationsobjekte erstellt. Da Drupal 8 standardmäßig das Überschreiben vorhandener Konfigurationsobjekte nicht erlaubt, kann die Migrations-Upgradekommandos nicht verwendet werden, um Migrationen nach migrate-upgrade --configure-only auszuführen. Stattdessen wird migrate-import verwendet.
• Wenn eine benutzerdefinierte Migration erstellt und importiert wurde (über die UI oder drush config-import), verwenden Sie migrate-import, um die Migration auszuführen.

Profi-Tipp: Wenn Sie benutzerdefinierte Migrationskonfiguration importiert haben und diese aktualisieren und erneut importieren müssen, verwenden Sie das Modul Configuration Update Manager.

migrate-rollback (mr)

Bereitgestellt vom Modul Migrate Tools. Wird verwendet, um eine Migration zurückzusetzen. Häufig genutzt zum Testen oder wenn Probleme auftreten und man von vorne beginnen möchte. Verwenden Sie den Befehl mit Migrations-ID oder Gruppe.

Beispiele

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

migrate-stop (mst)

Bereitgestellt vom Modul Migrate Tools. Stoppt eine laufende Migration.

Beispiel

drush migrate-stop migration_id

migrate-reset-status (mrs)

Bereitgestellt vom Modul Migrate Tools. Setzt den Status einer aktiven Migration zurück auf "wartend".

Beispiel

drush migrate-reset-status migration_id

migrate-messages (mmsg)

Bereitgestellt vom Modul Migrate Tools. Zeigt Nachrichten im Zusammenhang mit einer Migration an. Nützlich bei Fehlern während der Migration, um Gründe und Ursachen zu sehen.

Beispiel

drush migrate-messages migration_id

migrate-fields-source (mfs)

Bereitgestellt vom Modul Migrate Tools. Listet Felder auf, die in der Quelle zum Mapping verfügbar sind.

Beispiel

drush migrate-fields-source migration_id