Moving data to Drupal 8
Moving Up
Moving data from a different technology, such as migrating an old website from Drupal 6 or importing a database of news articles into Drupal 8, can be a daunting task. In Drupal 7, data migrations were possible using the contributed Migrate [1] module. The new Migrate API in Drupal 8 is based on the same methodologies for moving your data into Drupal (see the "Experimental Status" box). The Migrate API is excellent for upgrading from Drupal 6 or 7 and for one-time imports of large datasets. In this article, I look briefly at Drupal-to-Drupal upgrades and provide an in-depth example of migrations, including custom Source, Destination, and Process plugins.
Experimental Status
The Migrate API is still considered experimental (alpha stability) as of Drupal 8.1. At some point, it will be fully supported, but for now, you need to keep a few things in mind:
- There may be bugs (including security and data integrity issues).
- There is no guarantee of backward compatibility. The API could change with any patch.
- There is no upgrade path between updates. You will need to uninstall and reinstall the module after applying updates.
This doesn't mean that the Migrate API is useless in its current state. Far from it. Drupal 8 has all the tools necessary to import your data.
Drupal-to-Drupal Upgrades
The Migrate API comprises three modules in Drupal 8 core (Figure 1). You might need to enable one, two, or all three modules depending on your requirements. The Migrate module contains the main API used to define and run migrations. Migrate Drupal provides plugins for upgrading from an older version of Drupal. Migrate Drupal UI contains the interface for the official upgrade from Drupal 6 or Drupal 7. Before diving into custom migrations, I'll take a quick look at the Migrate Drupal UI module.
In theory, the Migrate Drupal UI module is a one-stop shop for Drupal upgrades. To try it out, make sure you are logged in as User 1
and navigate to the upgrade form at /upgrade
. Follow the prompts to connect to an old Drupal 6 or 7 database and click Review upgrade
(Figure 2). The module builds all the migrations needed for an entire upgrade.
The upgrade process has been tested for core upgrades but depends on contributed modules providing their own upgrade paths. Most Drupal sites use many contributed modules, and after you click Review upgrade , you will see a list of missing upgrade paths (Figure 3). Before you can use this UI, you will need to wait for contributed modules to provide an upgrade path or create your own. Drupal-to-Drupal upgrades via the UI are all or nothing.
A better solution (for now) is to build your own custom migrations (see the "Migration Help Hint" box) by building a new Drupal 8 site from scratch, including content types and other configurations, instead of migrating everything; then, run custom migrations to import discrete pieces of content from the old site. Building a new site from scratch lets you use the latest modules and best practices instead of working around a legacy system. This method also gives you an opportunity to clean up data as it is imported.
Migration Help Hint
When searching for migration help online, make sure to limit your results to the past six months. The Migrate API has been through many iterations during the development of Drupal 8, and old tutorials and blog posts may no longer be accurate.
Custom migrations are also used if you are migrating data from a non-Drupal source.
Building Custom Migrations
To write custom migrations, you should be comfortable managing Drupal 8 configurations in the YAML format. For more advanced migrations, you should be able to perform basic object-oriented tasks like extending a class, overriding methods, implementing an interface, and working with PHP annotations.
A Drupal migration is a configuration object consisting of a source and a destination. The source could be another database, a .csv
-formatted file, or even content scraped from an HTML document. The destination is a component of Drupal where data is saved, such as an entity (node, user, etc.) or configuration (content type, vocabulary, etc.). When the migration is executed, a row of data is fetched from the source, and each field is mapped to the destination using a process plugin. Different process plugins are used to manipulate the data before it is saved to the destination. Figure 4 shows this migration workflow.
Two contributed modules help configure and run custom migrations: Migrate Plus [2] and Migrate Tools [3]. Migrate Plus provides additional API tools and allows you to group similar migrations. It also includes a number of example migrations. Migrate Tools adds Drush commands to list, import, and roll back individual migrations. As of this article, Drush is the only way to run custom migrations, but a UI is currently in progress. You can follow the UI progress in the Migrate Tools issue queue [4].
Migration Example: Pets
Looking at an example is a great way to learn. Imagine you have a database full of information about dogs and cats and their owners. You just built a Drupal 8 website with a Pet content type and want to migrate the pet data. Pet owners become Drupal user accounts and pets are imported into Pet nodes. In the source database, the Pet table contains five fields:
pid
– Unique pet IDoid
– Owner IDtype
– Type of pet (dog or cat)name
– Pet's namepicture
– Photo of the pet
The Owner table contains three fields:
oid
– Unique owner IDname
– Owner nameemail
– Owner's email address
To import this data, you need to create two migrations and a migration group, along with custom source, destination, and process plugins.
Buy this article as PDF
(incl. VAT)