A Simple Drupal 7 to Drupal 8 Migration

It probably won't be much of a surprise to hear that there's a lot of excitement around these parts about Drupal 8. With the release candidates coming out recently and November 19, 2015 announced as the official release date, we've been putting a lot of work into our curriculum and recording new tutorials.

The developer in me has been itching to give it a try on a "real" project. The Drupalize.Me site itself is pretty complex: e-commerce (with recurring billing), video delivery, and piles and piles of content. Suffice it to say it's not a prime candidate for migration right now. Our blog however, is definitely a better prospect. Justin has a great new design for us. Amber has mentioned how much she'd like the new Drupal 8 authoring tools. The blog is relatively straight-forward which makes it a great way for our whole team to start using Drupal 8. So, as we start to think about upgrading our blog the first thing we're going to have to think about is data migration. Let's take a look at Migrate module, that's now part of Drupal core, and see how much work we might have ahead of ourselves.

Resources for Drupal-to-Drupal migration

My first stop on this adventure was to Drupal.org to check out the Migrate module's documentation. There are now four migration-related modules to know about:

• Migrate: The core API
• Migrate Drupal: Provides the classes needed to migrate Drupal to Drupal 8.
• Migrate Upgrade: Provides a simple user interface for running migrations from Drupal 6 or Drupal 7. There is ongoing work to include more of this UI in core.
• Migrate Plus: This is the current home for the pieces of Drupal 7's migrate functionality that didn't make it into core. It's home to things like plugins that support XML, CSV, and JSON data sources as well as proprietary databases like MS SQL or Oracle. This module includes another, Migrate Tools, which provides additional UI and drush commands for managing migrations. Note Migrate Plus is being split up into several smaller modules early next week. Mike Ryan provides more information about the split on his blog.

In addition, core modules that have migration paths written will have migration plugins within their own directories (see the user or taxonomy module for examples).

The next resource I visited was the Executing a Drupal 6/7 to Drupal 8 upgrade handbook page on Drupal.org. As this page points out, the bare bones of what you need to test a migration are:

• A local environment for your source site
• A local Drupal 8 site
• The Migrate Upgrade module
• Drush 8.x (or dev)

Once you have these basics in place you can proceed with a migration from either the UI or using Drush.

A cautionary tale

Drupal 8 is still in the release candidate phase (as of the time of writing this post), and there are a list of known issues with the Drupal-Drupal migrate path as well that will likely persist into 8.0.0. Probably the biggest issue for this particular migration is that Views are not yet being migrated automatically. The other issue I ran into was with the input formats on our current site. One of our input formats depends on a custom module that hasn't been ported to Drupal 8 yet.

Most problems you'll run into attempting a migration right now will fall into one of these two categories:

• missing migration paths
• contributed modules that need to be ported to Drupal 8

Before actually starting a migration, it's probably a good idea to identify the contributed modules you're using on your site and see which ones have Drupal 8 versions already available to test. As for the migration paths, this is one place the Migrate UI comes in really handy, as you can see in this screenshot:

Screenshot: Available migration paths

Prepare to migrate

To get started, on my local Drupal 8 site I've enabled the Migrate, Migrate Drupal and Drupal Upgrade modules. With these modules enabled, we can now visit the upgrade form (at the path /upgrade). Here you'll be presented with another warning about not using your live site as the data source, as well as some other reminders about enabling modules and database access.

Next you'll be asked to specify the credentials and location of your source database and files. After entering that information you'll be presented with a list available and missing migration paths. This list should give you a pretty good indication of what might be missing, and how much work you'll need to do in order to get your new Drupal 8 site really ready for a migration.

Screenshot: Missing migration paths

Limitations of Migrate's UI

If you proceed with a migration here from the UI, migrate will trigger an import of all of the available migrations. On my first attempt with a migration going this route I ran into a few issues. You can imagine that migrating all of the users, content and configuration for a site of this size takes a bit of time. Indeed, the first attempt lead to a batch failure during the user import process. I was (eventually) able to complete the migration by rerunning it from the web UI a handful of times.

Improve the migration process with Drush

Since the documentation goes out of the way to suggest using Drush to run migrations, I figured that was also worth a shot. The Migrate Tools module (bundled as part of Migrate Plus) provides several helpful Drush commands:

• migrate-import (mi): Perform one or more migration processes.
• migrate-manifest: Execute the migrations as specified in a manifest file.
• migrate-messages: View any messages associated with a migration.
• migrate-reset-status: Reset a active migration's status to idle.
• migrate-rollback: Rollback one or more migrations.
• migrate-status (ms): List all migrations with current status.
• migrate-stop (mst): Stop an active migration

When I run migrate-status, I get a list of all of the available migrations, status, total number of records, number imported and unprocessed and information about the last import. We can use migrate-import to run one particular migration. Using Drush to selectively run the migrations I needed for our blog dramatically sped up the total migration time for this particular site. Going forward I'll be using Drush, as the Drupal.org documentation recommends, rather than the UI to trigger migrations.

Create a migrate manifest YAML file

Once you've identified the migrations you're interested in, you can create a migrate manifest YAML file and use that to run a particular set of migrations. Documentation on drupal.org can help walk through the details of creating this manifest file. Once a manifest has been created the migrate-manifest command will run a migration for each item specified in the file.

Screenshot: Content migrated to Drupal 8

Impressions so far

I've been really impressed by how far along, and how polished the Drupal 8 migration process is already. There are definitely a couple of contribute modules we'll need to evaluate in order to have a fully working Drupal 8 blog, but I was able to migrate the bulk of our content without writing a single line of code.

In retrospect, as we continue to evaluate moving our blog to a Drupal 8 site I now need to go back and clean up the source site I use with Migrate. If we're going to split the blog off into a separate Drupal 8 site we won't need all of the content types or much of the other site configuration from the main Drupalize Me site. This will eliminate cruft from our new blog, and speed up the actual migration process itself. We'll also need to check in on a couple of key contributed modules, and rebuild a handful of Views (since they do not have a working migration path right now).

With the help of Migrate, the process of moving our blog to Drupal 8 is a lot less painful than I would have anticipated. Kudos to all the hard work that's gone into the Migrate collection of modules! With the official release of Drupal 8 right around the corner, maybe it's time to try migrating your site?