Simple Drupal 6/7 to Drupal 8 Migrations

Christopher Bloom (illepic)


Legacy Drupal 6 site needs a migration to new Drupal 8 site. We want to migrate settings, content types, fields, users, files, content. The Drupal 6 site database is accessible from the freshly installed Drupal 8 database.

Caveats & Considerations

  • Not "in-place" upgrade like Drupal 6 to 7

  • No UI, command line only

  • Lots of contrib
  • Migrations changed from config to "plugins" in Drupal 8.1. If you're starting fresh in 8.1, no worries.
  • We can migrate configuration as well as content in Drupal 8

Modules + Tools Required

  • A Migration Group is a collection of Migrations
  • A Migration is generally one YAML file.
  • A Migration contains
    • a source plugin: "read rows from source (D6)"
    • a processing pipeline: "transform raw source values into what the destination needs"
    • a destination plugin: "D8 understands what this thing becomes (nodes, users, entities)"
  • ​Processing plugins are simple PHP files to help massage data from source to destination

Looks like this all together as a module

A single Migration YAML file might look like this:

status: true
dependencies: {  }
id: upgrade_d6_node_page
  - 'Drupal 6'
migration_group: migrate_drupal_6
label: 'Nodes (page)'
  plugin: d6_node
  node_type: page
  nid: nid
  vid: vid
    plugin: default_value
    default_value: post
    plugin: default_value
    source: language
    default_value: und
  title: title
  uid: node_uid
  status: status
  created: created
  changed: changed
  promote: promote
  sticky: sticky
    plugin: default_value
    default_value: basic_html
    plugin: remove_strings
    source: body
      source: nid
      plugin: img_assist
      type: 'mid'
      plugin: iterator
        target_id: fid

      plugin: iterator
        target_id: fid
          plugin: default_value
          default_value: 1
    source: nid
    plugin: og_lookup
  plugin: 'entity:node'
    - upgrade_d6_user
    - upgrade_d6_node_type
    - upgrade_d6_file_media
  optional: { }

Tell D8 About Your D6 Database

In Drupal 8 settings.php, right next to your regular database configuration, add a db config FOR THE D6 SITE:

$databases['migrate']['default'] = array (
  'database' => 'dbname',
  'username' => 'dbuser',
  'password' => 'dbpass',
  'prefix' => '',
  'host' => 'localhost',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',

You now have configuration for

and $databases['migrate']['default']

This EXACT name for the D6 db config is extremely important:


Aight, D8. Generate a Migration


From the D8 site root, run:

drush migrate-upgrade --configure-only

Boom. D8 just took its best guess at figuring out all the fields, nodes, files, etc. (hopefully)

Now let's dump all this out as YAML files:

drush config-export --destination=/tmp/migrate

Many YAML files will now appear in /tmp/migrate. We're going to move all these to a custom module shortly.

Let's make a module so Drupal understands how to find this config


Use Drupal Console to generate a module for us

drupal generate:module

A series of questions will appear. We'll call the module custom_migration. Use the default options provided except:

  • Would you like to add module dependencies: yes
  • Module dependencies separated by commas: 
    migrate_drupal, migrate_plus


Create a folder in your new module:


Move our previously generated YAML to the new module:

cp /tmp/migrate/migrate_plus.migration.* \
    /tmp/migrate/migrate_plus.migration_group.migrate_*.yml \

Just make sure you do NOT include the default config group file called migrate_plus.migration_group.default.yml

Let's run it

Running drush migrate-status shows us the individual migrations D8 knows about

$ drush migrate-status
 Group: migrate_drupal_6              Status  Total  Imported  Unprocessed  Last imported       
 upgrade_d6_system_site               Idle    1      1         0             
 upgrade_d6_url_alias                 Idle    6972   0         6972                             
 upgrade_d6_file                      Idle    9914   3499      0             
 upgrade_d6_user_picture_file         Idle    281    281       0             
 upgrade_user_picture_entity_display  Idle    1      1         0             
 upgrade_d6_user                      Idle    1402   1133      0             
 upgrade_d6_file_media                Idle    9914   3495      0             
 upgrade_d6_book_blog                 Idle    822    0         822                              
 upgrade_d6_node_event                Idle    1351   0         1351                             
 upgrade_d6_node_forum                Idle    2305   0         2305                             
 upgrade_d6_node_guild_app            Idle    679    677       0             
 upgrade_d6_node_image                Idle    2243   0         2243                             
 upgrade_d6_node_page                 Idle    9      0         9                                

Run all migrations:

drush migrate-import --all


Next up:

Modify incoming data with built-in process plugins



  plugin: d6_file
  fid: fid
  # Skip any filename in the map below
      plugin: static_map
      source: filename
      bypass: true
        'gallery grid': ''
        preview: ''
        thumbnail: ''
        img_assist_properties: ''
        large: ''
      plugin: skip_contains
        - 'furiousraid'
      plugin: skip_on_empty
      method: row
      plugin: callback
      callable: basename
      source: filepath

Next up: Write your own process plugins
(in custom_migration/src/Plugin/migrate/process/ImagePath.php)


 * @file
 * Contains \Drupal\df_migration\Plugin\migrate\process\ImagePath.

namespace Drupal\df_migration\Plugin\migrate\process;

use Drupal\migrate\Annotation\MigrateProcessPlugin;
use Drupal\migrate\ProcessPluginBase;
use Drupal\migrate\MigrateExecutableInterface;
use Drupal\migrate\Row;

 * This plugin fixes d6 Image file names to be the actual filename from filesystem
 * @MigrateProcessPlugin(
 *   id = "image_path"
 * )
class ImagePath extends ProcessPluginBase {

   * {@inheritdoc}
  public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, 
                            $destination_property) {
    return basename($value);

Next up: Edit a migration YAML file, reload it in Drupal, and rerun a migration

# Rollback migration
drush mr upgrade_d6_node_page

# (Edit the migrate_plus.migration.upgrade_d6_node_page.yml file)

# Now, hard reload the file using Config Development module
drush cdi1 modules/custom/df_migration/config/install/migrate_plus.migration.upgrade_d6_node_page.yml \
    && drupal cr all

# Re-run this migration
drush mi upgrade_d6_node_guild_app

Next up: unbork a crashed migration

drush php-eval 'var_dump(Drupal::keyValue("migrate_status")->set('your_migration_name', 0))'

Super Helpful Resources

Made with