fromJune 2014

Migrate Overview


Two years into the development of Drupal 8, Dries Buytaert announced that Drupal 8.0 might ship without an upgrade path.

This unorthodox decision was made to support substantial improvements in Drupal’s major version upgrade process by introducing a robust new sub-system based on the popular contributed modules Migrate and Migrate D2D. The sub-system includes the Migrate module, which provides the basic framework and API, and the Migrate Drupal module, which provides the upgrade paths and framework to enable other Drupal-to-Drupal use cases in contrib.

The substantial wins with this new approach include the ability to move directly from Drupal 6 to Drupal 8 – as well as the possibility of providing more fine-grained control over the process – and the option of continuous content migration.

The migration team is working extraordinarily hard to be ready by the time that D8 is ready for beta. As of March 31, Migrate API has been committed to core. The last blocking issues for Migrate Drupal were resolved during the DevDays sprint, and the team will begin submitting patches for the D6 to D8 migration path to the core queue any day now.

A Drupal 6 to Drupal 8 upgrade without Migrate

Without the new API, an abbreviated move from Drupal 6 to Drupal 8 would have looked something like:

  1. Backup your database
  2. Update core and contrib to the latest version of 6
  3. Disable all contributed modules and switch to the core theme
  4. Delete the D6 code and replace it with D7 core code
  5. Run update.php
  6. Download the D7 contributed modules
  7. Enable the contrib modules
  8. Run update.php
  9. Repeat to upgrade from D7 to D8

For Drush users, the 'drush up' command would vastly simplify this, but two full upgrades — from 6 to 7, then 7 to 8 — would still have been required, inevitably losing data in each step.

A Drupal 6 to Drupal 8 Migration

As of Drupal 8, update.php will no longer be used for the two distinctly different purposes of minor version updates and major version upgrades. Update.php will continue to be used for updates within the same version, but Migrate will handle moving between major versions.
This will substantially change the way upgrades function. The first key difference when using Migrate is that instead of working within a single site, you'll have two: a source and a destination. In a D6 to D8 migration, for example, your D6 site will be the source and a fresh Drupal 8 install will be the destination. The abbreviated process will look more like:

  1. Install Drupal 8 core and desired contributed modules
  2. Enable the Migrate and Migrate Drupal modules
  3. Visit Manage » Configuration » System » Migrate
  4. Enter the database location and credentials for your Drupal 6 site
  5. Verify that all the modules you plan to migrate are enabled
  6. Migrate Configuration
  7. Migrate Content

You won't need to do anything with your source site; no disabling modules, no maintenance mode. Migrate strictly reads data from the source database, and any module with a migration path – whether core or contributed – will be migrated, provided that:

  • The source module is installed and enabled on the source site;
  • There's data in the source database;
  • The module is installed and enabled on the destination site.

What if I Need More Control?

If you don't want to migrate a module's data, you can disable it on the destination site before running Migrate. It’s clear, though, that many sites need more sophisticated or fine-grained control than that. At this point, it hasn’t been fully determined how much complexity will ultimately be supported by core’s user interface.

The current plan is to limit the core interface to the two-button process outlined above and to supply a more complex user interface for taking advantage of advanced API functionality in a contributed module. The core API itself includes the framework to enable implementation of the following features in contrib:

  • support for partial migrations
  • a plug-in system to support migrating from non-Drupal and non-SQL sources
  • the ability to write custom migrations that can transform your data in the process
  • continuous data migration

To access any of that functionality, at least initially, you’d either use Drush or Migrate Plus. As the user interface matures and new source plug-ins are written, functionality will be evaluated for inclusion in core on a case-by-case basis.

Continuous Data Migration

Previously, site upgrades were essentially a one-time thing. You might have had to try repeatedly to succeed, but ultimately, there came the point where you ran the entire upgrade and that was it.

Configuration migrations will still work that way. You’ll run the configuration migration once, and afterward, you’ll make additional adjustments manually. Where content is concerned, however, the API allows for a continuous approach. The vision is that using either Migrate Plus or Drush, each time you migrate content, anything new will be imported and content that’s been updated since the last run will be re-imported, making it possible to keep your D6 site in production, with users adding and editing content while you refine and QA your new D8 site.

The move from Update.php to Migrate API promises greater power, flexibility, accuracy, and ease for site administrators. A basic site will use the 2-button core-supplied user interface. Sites of moderate to intermediate complexity will be able to do considerable configuration through the Migrate Plus interface. Most complex sites, however, will likely require the creation of custom code to fully migrate a site, but the straightforward syntax and loosely coupled API is intended to support that inevitability. Complex sites with large datasets may also prefer using Drush to perform migrations due to its ability to manage memory and split large tasks among multiple batches in order to avoid resource exhaustion.

What’s Next?

Migrate is still under heavy development at the time of this writing. So far, the overall vision has been consistent over the six months of the project, but exactly which features will be split into core, Drush, or Migrate Plus may vary. Join the Drupal Group at for the current status.

What is a Migration?

An individual migration consists of a source plugin, a process plugin, and a destination plugin.

  • The Source plugin extracts the source rows. Custom modules and changes to the schema mean it’s not at all uncommon that you’ll need a custom source plugin to migrate non-standard parts of your site.
  • The Process plugins prepares the data for the destination. Many existing process plugins will serve even for custom source plugins, but some sites may need custom process plugins.
  • The Destination plugin saves the data in the destination. Custom destination plugins are seldom, if ever, required. Chances are if you’re writing one, you’re doing it wrong.

The three plugins are defined in a YAML configuration entity, which also describes groups and dependencies.

How to get involved

Image: ©LanceMcCarty