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.
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:
- Migrate Drupal
- 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:[email protected]st/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.
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 :
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:
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.
process: key, change the values for
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
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.