Skip to main content

Blog Post

Easier Drupal 7 to 8 Migrations with Migrate Pack

by Jay Callicott
September 16, 2019

The Problem with Upgrades

One of the more challenging tasks when upgrading Drupal from version 6 to 7 to Drupal 8 is the upgrade/migration process. We already know that themes and modules have to be rebuilt or otherwise ported when upgrading, but even migrating content can be a time-consuming chore.

The great news is that Drupal 9 might be the last big Drupal upgrade you ever have to deal with thanks to its backward-compatibility. That said, let’s zoom in on the problem at hand and address how we can make the last big upgrade you’ll ever be tasked with go more smoothly.

Errors halt migration

What can be frustrating about upgrading from Drupal 7 to 8 is that during the process there is a good chance your new Drupal 8 build will run into a field, entity or plugin that it doesn’t understand. This can lead to uncaught exceptions which then leads to an error and an incomplete migration. 

In some cases, you find the right contributed module or patch that will add a migration path for the configuration in question and the error is resolved on the next pass. More often than not, however, you will find that no such path exists and you have to deal with the error yourself. This could entail either updating the migration yml config to skip or reroute the configuration, perhaps by writing a custom migrate plugin. It’s possible you have to repeat this step multiple times until you have addressed each error that prevents a successful migration.

One problem with Drupal upgrades is that by default it assumes you want to upgrade everything from your Drupal 6 or 7 site. The Drupal upgrade will try to migrate some configuration that is honestly rarely needed, such as theme and system configuration. It’s more typical that developers will want a subset of the content and configuration from the previous version of Drupal.

Introducing Migrate Pack

migrate pack logo

We decided to take a different approach with migrations, particularly the early stage where you are trying to get through that first pass successfully. It’s this step where you want to grab as much content and configuration “as-is” into Drupal 8 so that you can start engineering the new site in earnest.

Migrate Pack’s Approach

The Migrate Pack module, hosted on Drupal.org, is an opinionated solution with the goal to capture 80% of the content and configuration you need without errors and without manual intervention.

Migrate Pack, first of all, will skip about half of the migration configuration that typically gets imported and then discarded as a way to cut down on the “cruft” that might weigh down a migration. This configuration can be overridden to further dictate which migrations will be included or skipped.

Next, this feature will attempt to avoid some common errors with things like invalid links or entity bundles that don’t exist. Rather than halt the migration with a fatal error, a notice will get logged which can be reviewed after the process is completed. 

Finally, Migrate Pack uses configuration to skip entities and bundles that do not have a known migration path. This again allows for the migration to complete with warnings being logged along the way. All of these settings can be customized per project. We think this results in a smoother process overall.

Using Migrate Pack

By leveraging Composer we hope to bundle the various modules you’ll need to get started quickly, even if you do not have a lot of experience with migrations.

The usage for this project is fairly straightforward. The first step is requiring the feature using Composer to download the module and all of its dependencies:

$ composer require drupal/migrate_pack

Once that is done you will enable the module to enable those dependencies:

$ drush en -y migrate_pack

While Drupal can be migrated through the UI, it’s usually easier to use drush commands provided by the migrate_upgrade module (which we enable by default). The drush “migrate:upgrade” command adds the configuration you will need. Below is a common example of the full command with parameters. You will want to examine your options with the “--help” parameter the first time you run this command.

$ drush --yes migrate:upgrade --legacy-db-key drupal7 --legacy-root sites/default/files --configure-only

After Drupal 8 generates the migrate configuration you can test drive a full migration or limit the migration in any number of ways. The “--all” command will attempt to execute all migrations, example below:

$ drush migrate:import --all

With Migrate Pack’s overrides you should have fewer errors (hopefully none) on the path to a successful first pass at migration.

Finally, it’s time to export your configuration. This can be done with the drush “config-export” command (see below):

$ drush config-export -y

The idea is that now the work begins to remap configuration, integrate custom plugins and any other development required to complete the desired full migration. As mentioned, Migrate Pack has its own settings.yml that will be exported to your configuration which can be adjusted as needed. If you run into any errors or problems along the way we recommend you create issues in the project issue queue.

Next Steps

We think that this feature can be a great tool to bust through errors that typically hamper a Drupal upgrade.  We would love for you to give this module a try and help make it more robust so that Drupal developers can complete migrations faster with fewer headaches along the way.

For issues and roadmap be sure to check out the project page and issue queue for the latest updates.

Got general feedback or questions? Use the comments below or hit me up on Twitter @drupalninja 

Meet team member, Jay Callicott

Jay is an engineer and leader with a passion for creating technical solutions that solve real-world problems. As a long-time advocate for Drupal and Open Source, he has spent over a decade speaking, writing, and developing enterprise solutions that advance Open Source worldwide.

Since 2009, Jay has worked in a variety of roles for Mediacurrent. For the first 6 years, he focused his efforts on perfecting his craft as an engineer. From Drupal consultant to Senior Developer, then Lead Architect, Jay created solutions and led teams that delivered dozens of enterprise websites.

In 2015, Jay was promoted to Director of Development where he was tasked with hiring developer talent and implementing processes and best practices for the team. Jay also split his time as a lead architect, launching several large projects during this period.

A few years later, Jay moved into his current role as VP of Technical Operations. Jay’s primary responsibilities are working with the revenue team to acquire and retain customers, overseeing Security, DevOps, and IT roles, and leading Mediacurrent’s technology vision. He also helps lead the development of tools and solutions, including the Rain distribution, which won Acquia’s “Open Source Giants” award in 2019.

Currently, Jay is a big proponent of decoupled architecture and the JAMStack approach to web development. Read more about Jay’s thoughts in “The State of Drupal in 2019

Learn more about Jay >

Related Insights