The Drupal Migrate API and related tools are used to import data such as content, users, and configuration values into Drupal. The system consists of three core modules: Migrate, Migrate Drupal, and Migrate Drupal UI. A growing number of contributed modules also aid in writing and executing a migration. In Drupal 7 the migration API is provided by the Migrate contributed module.
As a developer you’ll use the Migrate API in Drupal to write migration plugins that extract data from a defined source, transform it to match with your Drupal data model, and then load it into Drupal via the Entity or Config APIs. You’ll then use one or more contributed modules to execute, rollback, and debug your data migration.
Example tasks
- Import data from a CSV file, MySQL database, or other source into Drupal
- Migrate from WordPress or another CMS to Drupal
- Provide an update path for users of your module when porting it to the current version of Drupal.
Confidence
As of Drupal 8.5.x the core Migrate API is considered stable and no major backwards compatibility breaking changes are expected. If you're writing custom migrations, you're good to go.
Drupalize.Me resources
Our extensive migration course covers everything you need to know to get started writing, executing, and debugging Drupal migrations.
We recommend the following starting points:
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 the latest version of Drupal. This tutorial provides an overview and links to additional tutorials where you can learn more about how all the individual parts work.
By the end of this tutorial you should have a better understanding of what the migration system is capable of and know where to find more information about how to use it.
Upgrading is the process of moving your site from a previous major version of Drupal to a newer version, for example from Drupal 7 to Drupal 8 or Drupal 9 to Drupal 10.
Migration plugins are the glue that binds a source, a destination, and multiple process plugins together to move data from one place to another. Often referred to as migration templates, or simply migrations, migration plugins are YAML files that explain to Drupal where to get the data, how to process it, and where to save the resulting object.
Source, process, and destination plugins do the heavy lifting in each phase of the ETL process in a custom migration. We need to choose which plugins we want to use for each phase, as well as map fields from our source data to fields at our destination. A migration YAML file glues it all together and gives it a unique name that we can use to run it.
In this tutorial we'll:
- Determine what information we're going to move, and where we're going to move it to
- Install Migrate Plus and Migrate Tools which we'll use to run our custom migration
- Write a custom migration plugin (configuration) YAML file that will work with Migrate Tools
By the end of this tutorial you should be able to write a custom migration YAML file and understand how to choose the source, destination, and process plugins that will do the work.
External resources
-
Migrate API guide (Drupal.org), and Migration API documentation (api.drupal.org)
- Drupal.org contains documentation about concepts, while api.drupal.org contains implementation details. Use this to locate documentation about the code that makes up the Migrate API, as well as examples of how to configure and use common destination and process plugins.
-
Migrate Plus module (Drupal.org)
- The Migrate Plus module contains some essential additional tools for working with migrations, many of which will likely be included in core in future versions. It also contains two carefully documented sub-modules that provide examples of implementing migrations in code. Use this for the additional enhancements and if you like to learn by reading through example code.
-
Drupal 8 Migrations by Example (2017.tcdrupal.org)
- Presentation covering the concepts and terminology of the migrate system followed by some examples including populating address, date, image, and file fields. Watch this presentation to get an overview of concepts used by the system, and get some insight into how two developers have used the migrate API on various real-world projects.
- Join the #migration channel on Slack
There are so many different permutations of things that someone might want to migrate that it would be impossible for any guide to cover all of them. We’ll keep a running list of some of our favorite examples below. Use these resources to see examples, usually with code, of how someone else solved a specific task with the Migrate API.
- Migrate Translated Content from Drupal 6 to Drupal 8 (evolvingweb.ca)
- Migrate Translations from CSV, JSON or XML to Drupal 8 (evolvingweb.ca)
- Migrating from WordPress (attendesigngroup.com)
- Stop Waiting for Feeds Module: How to Import RSS in Drupal 8 (ohthehugemanatee.org)
- Migrate a custom JSON feed in Drupal 8 with Migrate Source JSON (jeffgeerling.com)