Upgrade Your Drupal Skills
We trained 1,000+ Drupal Developers over the last decade.
See Advanced Courses NAH, I know EnoughCustom Drupal-to-Drupal Migrations with Migrate Tools
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:
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:[email protected]/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.
About Drupal Sun
Drupal Sun is an Evolving Web project. It allows you to:
- Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
- Facet based on tags, author, or feed
- Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
- View the entire article text inline, or in the context of the site where it was created
See the blog post at Evolving Web