Custom Drupal-to-Drupal Migrations with Migrate Tools

Image

Editor's note: To learn how to upgrade/migrate to Drupal 8, follow our full Drupal 8 Migration Guide.

Drupal 8 core provides support for Drupal-to-Drupal migrations. Since there is no direct upgrade path for Drupal 6 or 7 to 8, you should become familiar with the migration system in Drupal, as it will allow you to migrate your content from previous versions to Drupal 8.

In this post, which is aimed at advanced Drupal users, we will discuss how you can conduct a custom Drupal-to-Drupal to migration using core, and contributed modules, along with Drush.

If you have not yet read Mike Ryan's excellent blog post about the changes to the Migrate System in Drupal 8.1, I would highly recommend it.

Preparation

To be able to run custom Drupal-to-Drupal migrations in Drupal 8, you will need the following:

• Drupal 8.1 (or greater) installed
• A database backup from your Drupal 6 or 7 site, and optionally, your sites/default/files directory from your Drupal 6 or 7 site
• A database backup of your freshly installed Drupal 8.1

Enable the following modules in your Drupal 8.1 site:

Core:

• Migrate
• Migrate Drupal

Contributed:

• Migrate Upgrade (drupal.org/project/migrate_upgrade)
• Migrate Tools (drupal.org/project/migrate_tools)
• Migrate Plus (drupal.org/project/migrate_plus)

After enabling the required modules, add an additional database definition to your settings.php for your Drupal 8.1 site. See Drupal\migrate\Plugin\migrate\source\SqlBase

// Database entry for `drush migrate-upgrade --configure-only`
$databases['upgrade']['default'] = array (
  'database' => 'dbname',
  'username' => 'dbuser',
  'password' => 'dbpass',
  'prefix' => '',
  'host' => 'localhost',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
);
// Database entry for `drush migrate-import --all`
$databases['migrate']['default'] = array (
  'database' => 'dbname',
  'username' => 'dbuser',
  'password' => 'dbpass',
  'prefix' => '',
  'host' => 'localhost',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
);

Generate a migration

With these steps complete, it's time to generate a migration. Open up a terminal, and issue the following command, from your Drupal 8.1 root directory:

drush migrate-upgrade --configure-only

If you didn’t create an entry in your settings.php you can pass your database credentials for your Drupal 6 or 7 site, and optionally, the path to the files directory like so:

drush migrate-upgrade --configure-only --legacy-db-url=mysql://dbuser:dbpass@localhost/dbname --legacy-root=/path/to/sites/default/files

This command will generate migration configuration entities in the active configuration store, using migration plugins in Drupal core. Check out the tutorial, Configuration Data Storage, to learn more about the configuration system in Drupal 8.

Create a custom migration module

At this stage, we need to create a custom module for our migration, in your Drupal 8.1 site. You can do this manually, or using Drupal Console, like so:

drupal generate:module

// Welcome to the Drupal module generator
 
Enter the new module name:
> custom_migration
    
Enter the module machine name [custom_migration]:
>
    
Enter the module Path [/modules/custom]:
>
    
Enter module description [My Awesome Module]:
> A custom Drupal-to-Drupal migration
    
Enter package name [Custom]:
>
    
Enter Drupal Core version [8.x]:
>
    
Do you want to generate a .module file (yes/no) [no]:
> no
    
Define module as feature (yes/no) [no]:
> no
    
Do you want to add a composer.json file to your module (yes/no) [yes]:
> 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
    
Do you confirm generation? (yes/no) [yes]:
> yes
    
Generated or updated files
Site path: /Users/willwh/Sites/drupal
1 - modules/custom/custom_migration/custom_migration.info.yml
2 - modules/custom/custom_migration/composer.json

Export site configuration

Create the directory custom_migration/config/install , which is where we will store our custom migration.

We can now export our site configuration, which will include our generated migration configuration entities. If you’re not familiar with the configuration system Drupal 8, you should check out our Configuration Management tutorials, specifically Manage Configuration with Command Line Tools.

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

Copy migration configuration to custom module

Next, we need to copy the migration configuration generated by drush migrate-upgrade --configure-only to our custom_migrate/config/install.

These files will be at /tmp/migrate and begin with migrate_plus.

Caution

Warning! Make sure you do not copy the default configuration group that is defined by migrate plus, i.e. migrate_plus.migration_group.default.yml.

Use the following command, and replace the last argument with the correct path to your custom module’s config/install location:

cp /tmp/migrate/migrate_plus.migration.* /tmp/migrate/migrate_plus.migration_group.migrate_*.yml /path/to/your/module/config/install/

Edit your module’s migrations

At this point, you can simply remove any of the migrations you don’t need, along with any dependencies on them. You can also now edit the migrations contained in your module to your liking.

For example, if you don’t want to migrate blocks from your previous site, you would delete the following files at custom_migration/config/install :

• migrate_plus.migration.upgrade_block_content_body_field.yml
• migrate_plus.migration.upgrade_block_content_type.yml
• migrate_plus.migration.upgrade_d7_block.yml
• migrate_plus.migration.upgrade_d7_custom_block.yml

Customize migrations with process plugins

Migrations may also be customized with process plugins.

Let’s say you’re migrating from a Drupal 7 site. If you wanted to map a node type from a previous Drupal version to a different node type in Drupal 8, you could accomplish this with the default_value process plugin.

For example, given this migration template:

• migrate_plus.migration.upgrade_d7_node_blog_post.yml

In the process: section of the migration, take note of the following:

process:
  type: type
  name: name
  description: description
...

Instead of mapping the node type in Drupal 7 to one of the same name in Drupal 8, which, in my example would import the blog_post content from Drupal 7, to a content type of blog_post in Drupal 8, we can use the default_value plugin, and specify a node type of a different name.

In the process: key, change the values for plugin to default_value and value to the machine name of your desired node type.

process:
  type:
    plugin: default_value
    value: desired_node_type
  name: name
  description: description
  help: help
  title_label: title_label
  preview_mode: constants/preview
  display_submitted: display_submitted
  new_revision: options/revision
  create_body: create_body
  create_body_label: body_label

Run the customized migration

To run your migration, you must import your clean backup of Drupal 8.1, enable the required modules above, and your new custom_migration module.

You can check that you have everything set up correctly by running drush migrate-status. You should see a list of all of the migrations you have defined in your module.

A portion of my custom migration status looks like this:

Group: default                                  Status  Total  Imported  Unprocessed  Last imported
 upgrade_block_content_type                      Idle    1      0         1
 upgrade_d7_dblog_settings                       Idle    0      0         0
 upgrade_d7_image_settings                       Idle    0      0         0
 upgrade_d7_node_settings                        Idle    1      0         1
 upgrade_d7_search_settings                      Idle    1      0         1
 upgrade_d7_url_alias                            Idle    4953   0         4953
 upgrade_d7_user_flood                           Idle    0      0         0
 upgrade_d7_user_mail                            Idle    1      0         1
 upgrade_menu_settings                           Idle    0      0         0
 upgrade_search_page                             Idle    1      0         1
 upgrade_taxonomy_settings                       Idle    0      0         0
 upgrade_text_settings                           Idle    0      0         0

To execute your migration, run the following:

drush migrate-import --all

Stay tuned…

We will cover this process in much greater detail in our upcoming Migrate to Drupal 8 tutorials, but I hope this will help you get started in migrating to Drupal 8!

Update (May 6, 2016): Our Drupal 8 Migration Guide is underway. Check out the latest tutorials on Drupal-to-Drupal migrations here.