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
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.
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.
Got general feedback or questions? Use the comments below or hit me up on Twitter @drupalninja