Drupal 8 Migration Guide

Whether you're updating from Drupal 6 or Drupal 7, or importing data from some other source, you need to know about the migrate system in Drupal 8. This guide provides a comprehensive look at the features of the Drupal 8 migrate API for both Drupal-to-Drupal updates, and migrating from any external datastore into Drupal.

This guide is for anyone who wants to:

  • Update from a previous version of Drupal to Drupal 8
  • Import data from external datasources including MySQL, CSV, JSON, or XML into Drupal 8
  • Maintains a contributed module and wants to provide an update path from Drupal 6 and 7

Where should I start?

If you're new to the Migrate API, start from the beginning and get an overview of how the system works and how all the pieces fit together. This is essential background information for anyone wanting to migrate data into Drupal. Additionally, part of performing any migration is planning and preparation. Migrations involve preparing and analyzing your source data, building a new website that data can be migrated into, and lots of testing, rolling back, and testing again, in order to get everything right.

Update or migrate?

The Drupal core migration system is used for both importing data from custom sources, and for migrating content and configuration from previous versions of Drupal into Drupal 8 -- effectively updating your site from one major version to another. Depending on which of these two tasks you're performing you'll use the tools in different ways.

Updating from previous versions of Drupal to Drupal 8

If you're migrating from a previous version of Drupal, start with our Preparing for a Drupal-to-Drupal Migration tutorial. From there you'll learn how to perform a basic update using either the built in UI or the contributed Drush commands, as well as some common best practices to help things go as smoothly as possible. If you're looking to customize your Drupal-to-Drupal migration a bit, continue through the tutorials on writing custom migrations, and then we'll go in-depth on how to use those skills to tailor the Drupal-to-Drupal update process to your specific use-case.

Importing data from external sources

If you're importing data from a non-Drupal datastore, start with Set up Migrate Demo Site and Source Data . We'll walk through the process of connecting the migrate system to an external data source, writing custom migration paths, using custom process plugins to transform data during import, and best practices for executing your custom migrations. We'll primarily look at using an external MySQL database as our data source, but the techniques learned will apply to any data source. We'll also discuss how to extract data from CSV, JSON, and XML sources.

The Drupal 8 migration system is currently a work-in-progress; there are still some kinks, and best practices continue to evolve. As with all of our Drupal 8 material, we're committed to keeping these tutorials up-to-date as work progresses. We'll keep an eye on the changes that are happening both in Core and with the main contributed modules and make adjustments as needed.