Updating Using Drush

Upgrade Using Drush

Drush is a command-line shell and scripting interface for Drupal. Upgrading to Drupal 8 using Drush is an alternative to using the browser-based UI. It is especially useful for migrating complex sites as it allows migrations to be run individually and rolled back as needed.

Installing Drush with Composer

Drupal sites can be built using Composer. If you use drupal-composer/drupal-project as a project template, Drush is already included as a dependency in the project’s composer.json file.

If Drush isn’t listed as a dependency in your project, you can install it via the command line:

composer require drush/drush

Note: Use Drush 9

Due to issues with Drush 10, it’s recommended to install Drush 9 with composer require drush/drush:^9.0 (e.g. version 9.7.2).

To check your Drush version:

drush --version

Required Drupal Modules

To migrate using Drush, you need to download and enable the following contributed modules:

• Migrate Upgrade: Enables Drush support for upgrading from Drupal 6 or 7 to Drupal 11.
• Migrate Plus: Adds enhancements to the core migration functionality.
• Migrate Tools: Provides Drush commands used below.

IMPORTANT! Ensure you choose the correct version for each module to match your core Drupal version. See the list of upgrade modules for guidance.

Define the Source Database

Example configuration for source Drupal 6/7 site. If using a table prefix, specify it. Below is a sample using Lando. Includes the default local development database connection:

$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',
];

name: mywebsite
recipe: drupal8
config:
  webroot: web
services:
  d7db:
    type: mariadb
    creds:
      user: drupal7db
      password: drupal7db
      database: drupal7db
    portforward: true

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

Generate Migrations with migrate-upgrade

drush migrate-upgrade (from Migrate Upgrade) is used to generate migrations. Use the --configure-only option to generate but not run them:

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

Running Specific Migrations with migrate-manifest

To control execution of a group of migrations, use Migrate Manifest. Define the migrations you want in a YAML manifest file. Run with:

drush migrate-manifest --legacy-db-url=mysql://user:pass@localhost/db manifest.yml

Common Drush Migration Commands

• migrate-upgrade: drush migrate-upgrade --legacy-db-key=migrate
• migrate-status (ms): View migration statuses. drush migrate-status
• migrate-import (mi): Run migrations. drush migrate-import migration_id
• migrate-rollback (mr): Rollback a migration. drush migrate-rollback migration_id
• migrate-stop (mst): Stop an active migration. drush migrate-stop migration_id
• migrate-reset-status (mrs): Reset a stuck migration status. drush migrate-reset-status migration_id
• migrate-messages (mmsg): View migration messages. drush migrate-messages migration_id
• migrate-fields-source (mfs): View source fields. drush migrate-fields-source migration_id