Page tree
Skip to end of metadata
Go to start of metadata

General Overview

There are a lot of good articles out there that can help you with this.  This is more of specific examples on how to do it between 2 localhosts.

Some references:

Preparing for an Upgrade (READ FIRST)

Upgrade using the UI

Upgrade Using Drush

Drush Migrate Commands

UI Based Migration

Simple, but will write this up later. In the interim: check that out

Migrating with Drush

You will need a few extra modules to get started with this route: Migrate ToolsMigrate Upgrade & Migrate Plus

  • Read the module page to make sure you grab the appropriate version for your D8 core version.

Double check if you need any special modules for your content as mentioned in the Preparing for an Upgrade link above.

Also, check out Drupal 8 Migration Useful Drush Commands & Other Tips for quick tips on drush commands.


Currently can't enable Migrate Upgrade module - see issue:

Drupal VM

  1. Download & setup both the D7 and the D8 sites
  2. Enable the migrate, migrate tools, migrate upgrade & migrate plus modules in the D8 site
  3. In the D8 site run this

    drush migrate-upgrade --legacy-db-url=mysql://drupal:drupal@localhost/D7SITE_drupalvm --legacy-root=http://D7SITE.dvm --configure-only
    drush migrate-status
  4. You will see a list of all the items queued for migration.  You can either migrate them all or pick and chose.
    1. You can migrate all of the items with:

      drush migrate-import --all 
    2. OR you can be more granular and migrate only certain items:

      drush migrate-import {migration name} 
      drush migrate-import upgrade_d7_menu
      drush migrate-import upgrade_d7_node_news
      1. NOTE: it will tell you what other items you need to migrate with that singular migration peice when you try to import it.

Custom Migrations

Use this option if you need to be more granular in your migration.  You can also use this to change the names of items, etc.  There are a lot of great resources out there on how to do super duper custom configs.  This is just a simple example.

Note: This is for a local to local migration for testing  purposes.  Once you have a woring copy of what you need, I wrote an example of a Pantheon to Pantheon Migration below.


Currently can't enable Migrate Upgrade module - see issue:

Drupal VM

  1. Download & setup both the D7 and the D8 sites.
  2. Do the following in your terminal on your D8 site (change our YOUR-MODULE as need be):

    vagrant@dvm:/var/www/YOUR-SITE/web$ drupal gm
     // Welcome to the Drupal module generator
     Enter the new module name:
     > YOUR-MODULE Migrate
     Enter the module machine name [YOUR-MODULE_migrate]:
     Enter the module Path [/modules/custom]:
     Enter module description [My Awesome Module]:
     > The Migrate Template for YOUR-MODULE
     Enter package name [Custom]:
     Enter Drupal Core version [8.x]:
     Do you want to generate a .module file (yes/no) [yes]:
     > no
     Define module as feature (yes/no) [no]:
     Do you want to add a composer.json file to your module (yes/no) [yes]:
     Would you like to add module dependencies (yes/no) [no]:
     > yes
     Module dependencies separated by commas (i.e. context, panels):
     > migrate_drupal, migrate_plus, migrate_tools, migrate_upgrade
     Do you want to generate a unit test class (yes/no) [yes]:
     > no
     Do you want to generate a themeable template (yes/no) [yes]:
     > no
     Do you confirm generation? (yes/no) [yes]:
     > yes
    Generated or updated files
     1 - /var/www/YOUR-SITE/web/modules/custom/YOUR-MODULE_migrate/
     2 - /var/www/YOUR-SITE/web/modules/custom/YOUR-MODULE_migrate/composer.json
  3. In your settings.local.php add this to the top:

    $databases['migrate']['default'] = array (
      'database' => 'DRUPAL-7-SITE_drupalvm',
      'username' => 'drupal',
      'password' => 'drupal',
      'prefix' => '',
      'host' => 'localhost',
      'port' => '',
      'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
      'driver' => 'mysql',
  4. In the YOUR-MODULE_migrate module we created above, add a config/install folder

  5. In your D8 site run this:

    drush migrate-upgrade --legacy-db-key=migrate --configure-only
    drush config-export --destination=/tmp/migrate
    cp /tmp/migrate/migrate_plus.migration.* /path/to/YOUR-MODULE_migrate/config/install
    cd /path/to/YOUR-MODULE_migrate/config/install
  6. Then you can go through and remove the yml files you don't need.  Careful though, read the required dependencies at the bottom of each yml file.
  7. You should also have a yml file(s) with named like the following: migrate_plus.migration_group.GROUP-NAME.yml.  The default group name is migrate_drupal_7.  Open that file(s) up and edit the last line: shared_configuration: null to the following:

        key: migrate
  8. If you need to skip rows (ie fields, certain nodes, etc), this is a good tutorial on how to do so:
  9. If you need to alter data or do heavier customization you need to extend various migration and plugin classes. 
    1. Here is a quick article on Altering data during a Drupal 8 Migration
    2. There are also numerous articles out there as well to help you in this regard.
  10. Wipe and re-install your D8 site plus enable the custom module. You should only have the config you specified in the module now.

    1. You can check and then import with:

      drush migrate-status
      drush migrate-import --all 
    2. NOTE: Make a little script to help with testing this to remove failures, etc.  Use drush_print() in my hook_migrate_prepare_row() for fast debugging.  You will drop and import the DB over and over.  Here is a sample script:

      drush @drupalvm.YOUR-SITE.dvm sql-drop -y
      drush @drupalvm.YOUR-SITE.dvm sql-cli < ~/path/to/DB.sql
      drush @drupalvm.YOUR-SITE.dvm en YOUR-MODULE_migrate -y
      #drush @drupalvm.YOUR-SITE.dvm mi upgrade_d7_field
      #drush @drupalvm.YOUR-SITE.dvm mi upgrade_d7_field_instance
      drush @drupalvm.YOUR-SITE.dvm mi --all

Pantheon to Pantheon Migration Setup

  1. SFTP a file called secrets.json to your D8's files/private folder.
    1. Just put this in the file to make a legit json file: {}
  2. In your D8 site's settings.php put this at the bottom:

    # When on Pantheon, connect to a D7 database.
    $migrate_settings = __DIR__ . "/settings.migrate-on-pantheon.php";
    if (file_exists($migrate_settings) && isset($_ENV['PANTHEON_ENVIRONMENT'])) {
     include $migrate_settings;
  3. Create a file called settings.migrate-on-pantheon.php in your D8 sites/default folder and put this in it:

    $secretsFile = $_SERVER['HOME'] . '/files/private/secrets.json';
    if (file_exists($secretsFile)) {
      $secrets = json_decode(file_get_contents($secretsFile), 1);
    if (!empty($secrets['migrate_source_db__url'])) {
      $parsed_url = parse_url($secrets['migrate_source_db__url']);
      if (!empty($parsed_url['port']) && !empty($parsed_url['host']) && !empty($parsed_url['pass'])) {
        $databases['migrate']['default'] = array (
          'database' => 'pantheon',
          'username' => 'pantheon',
          'password' => $parsed_url['pass'],
          'host' => $parsed_url['host'],
          'port' => $parsed_url['port'],
          'driver' => 'mysql',
          'prefix' => '',
          'collation' => 'utf8mb4_general_ci',
  4. Install Terminus and the Terminus Secrets Plugin
  5. Run these commands on your local machine:

    export D7_MYSQL_URL=$(terminus connection:info --field=mysql_url D7-PANTHEON-SITE.PANTHEON-ENV)
    terminus secrets:set D8-PANTHEON-SITE.PANTHEON-ENV migrate_source_db__url $D7_MYSQL_URL
    terminus remote:drush D8-PANTHEON-SITE.PANTHEON-ENV -- migrate-upgrade --legacy-db-key=migrate --configure-only
  • No labels