As a developer or site builder, there will come a time when you have a lot of content to import into your Pantheon site—a need that will go beyond Feeds and will perhaps have related content, entity references and the like—that will make importing content a challenge. This path will lead you to Drupal’s Migrate module. In Drupal 8, this module is in core.
Much can be said about Migrate and how it works, but to give you the short version: it allows a new Drupal site to connect to a different source (such as another copy of Drupal or even another platform such as Wordpress). Once connected, it will pull content in, one piece at a time, and track it—in case it gets updated, or in case other content relies on it—so it can reconcile these complicated matters for you.
The Simplest Migration: Drupal to Drupal
To demonstrate the power of Migrate, we can do what is called a “drupal to drupal” migration on a site that is based on Drupal 6 or Drupal 7 and bring that content into a new Drupal 8 site.
Let’s look at the steps involved:
Import our old Drupal site into Pantheon if it is not there already.
Create a new Pantheon site to run a Drupal 8 site. Go through the install process.
Enable the experimental migration modules.
Run the “Migrate Upgrade” process.
After completing this process, you should have all of the configuration pertaining to the old site, such as site name, content types, fields, and other settings from the old site. With all of these elements in the site, the real magic can begin. The Migrate module will begin populating these things with content from your old site. If you have used Migrate in Drupal 7 this may be a surprise, that older version did not set things up for you and you had to manually map out all of the fields. The Drupal 8 version goes much further to make your life substantially easier.
Migration Upgrade, Step by Step
1. Import your existing site into Pantheon if it is not there already. A free sandbox account should be fine.
2. Create a new Drupal 8 site. Upon completion of the install process, remember to commit Pantheon’s settings.php file and switch to “Git” mode.
3. Go to the “Extend” page in Drupal 8, enable the Migrate, Migrate Drupal, and Migrate Drupal UI modules. See Figure 1.
4. After enabling the modules you will see a green message to notify you that the module has been installed, it ALSO provides a link to the upgrade form. See Figure 2.
5. Go to the /upgrade page or follow the link that appeared after enabling the module. See Figure 3.
6. Input the database credentials for the old site. See Figure 4. You can get these credentials from the Pantheon dashboard of the old site under “Connection Info” These database credentials can change as Pantheon containers update. You may need to update this information later if you intend to run migrations repeatedly over time. Over on the GitHub repo for Pantheon documentation, there is a discussion about different ways to automate and simplify the database connection setup. Stay tuned for a future blog post on running migrations through Drush when those recommendations are finalized.
7. Congratulations, you upgraded Drupal! Now it is time to review.
Reviewing the Migration
After you run the migration, you will want to do a full review to see what worked and what didn’t. This is an important step both for the developer and the site owner.
Things you should verify:
Did the site variables, such as site_name, and other site-wide settings come across?
Were all of the content types and fields created as you expected? If a field or type is missing, do you still need it in the new site?
What content came through, did you get all of the items you were expecting? You will find some occasional differences, such as user 1 is not being imported, because you created that user when you installed Drupal 8, not during migration. You may find some nodes fail due to problems with a field, etc.
Watch out for some of the following:
Missing filter formats can cause body text and other field data to go missing if the formatter was not available during the import. This could happen if you did not enable a contrib module, for example. If the filter does not yet exist for Drupal 8, you can get around this by implementing hook_migrate_prepare_row in a custom module to set those to use a different filter. This hook iterates over every single item that is imported, so you can update specific values as they are being imported.
User, node, entity, and file references may break, especially if a needed module was not enabled before you migrated. Depending on the version of Drupal you are migrating from you may need to use a patch (see the “migration system” component filter on the core issue queue) to enable support for these fields if they do not work. You would have to run the migration locally on your laptop if you have to do any patching.
Some fields or other data may not be relevant to your new site. You may want to delete these after importing, or you may want to consider overriding things using Drush and the migrate-upgrade command (from contrib, 8.x-2.x branch) to generate migration YML files you can use to augment the migrations.
Once you are satisfied that you have the content you need, you can finish your site building tasks and re-run the migration if you have not changed any structure. Re-running the migration will bring in the new elements that have been created since your last import.
Other Migrations & Next Steps
If you use contrib modules, you can take the migrations even further. For example, you can use the Migrate Source CSV module to create migrations that import from a spreadsheet. To work with it all you need to do is create some Drupal 8 configuration files: https://www.drupal.org/project/migrate_source_csv
You can also import from other platforms such as Wordpress. Currently the wordpress_migrate module is in development. Contributions are welcome. https://www.drupal.org/project/wordpress_migrate
If the approach taken here does too much you can create your migrations manually using YML files where you map out the fields by hand. If you wish to build the entire site from scratch in Drupal 8—including creating the content types, etc.—this may be the best approach.
Contrib modules for custom migrations:
Additional documentation:: Drupal, Drupal Planet