Advertising sustains the DA. Ads are hidden for members. Join today

Migrate

Note: The Migrate module documentation is, as befits a complex subject, always in need of improvement. The best way to contribute improvements is not comments on the documentation pages (unfortunately, there is no notification process to tell the authors of comments), but to submit a Documentation issue to the Migrate module issue queue.

For Drupal 8, see in-progress Migrate API in Drupal 8.

The Migrate module (V2) provides a flexible framework for migrating content into Drupal from other sources. It is important to recognize that the Migrate module is a developer's tool — if you do not have object-oriented programming skills in PHP, this module is not for you. The primary purpose is to provide the infrastructure for managing complex, large-scale site migrations. However, add-on modules can be developed on top of Migrate to provide a UI suitable for use by non-technical users for simpler migration cases — as an example, see the WordPress Migrate module for importing Wordpress exports into Drupal 7.

The Migrate module consists of:

  1. An API for defining and managing migration processes.
  2. A set of drush commands for running migration processes and obtaining status.
  3. The migrate_ui module, which provides visual status and details on defined migrations.
  4. The migrate_example* modules, which demonstrate many techniques used in defining migrations.

Features:

  1. An object-oriented architecture, allowing default behavior to be extended and/or overridden.
  2. Built-in support for PDO (DBTNG), XML, CSV, JSON, and native MSSQL and Oracle API sources; extendable for other sources.
  3. Built-in support for node, user, taxonomy term, comment, and file destinations; extendable for other destination entities and fields.
  4. Map tables maintain relationships between source data and the resulting Drupal objects.
  5. Import operations can be rolled back, allowing simple trial-and-error development of migration processes.
  6. Tools for managing dependencies between migrated content.
  7. Automated management of memory usage and framework for performance logging.
  8. A web UI supporting collaboration between stakeholders and implementers.

Object-oriented architecture

The Migrate V2 API consists of several classes representing data sources, Drupal destination objects, and the relationships between sources and destinations. This gives the migration implementer the flexibility to override any aspect of the migration process for specialized cases. Handlers also allow application-specific processing to be invoked at key points of the migration process.

Collaborative support

The bundled migrate_ui module, in addition to displaying the current status of migration processes, presents the details of how each migration is set up - in particular, the source and destination fields available and the mappings between them. Mappings can be annotated and linked to external tickets, so stakeholders and implementers can see the reasons for particular mappings and stay a click away from full details. Mappings can also be classified arbitrarily - for example, those which require stakeholder review can be set aside in their own group and highlighted. Also, any source or destination fields which have not been either mapped, or explicitly marked as unmapped, are highlighted so they don't fall through the cracks.

Advanced topics

For straight-forward migrations, the previous documentation pages should be enough to get you going. In more complex cases, the advanced

Caveats

Migrate is a powerful module - it can make massive changes to the destination site very quickly - so it pays to think carefully about

Contributed module support

Many contributed Drupal modules are responsible for maintaining data - they define new field types or entity types, or maintain custom

Cookbook

Here is a cookbook of useful tips and ideas for specialized applications - feel free to add your own Migrate V2 tricks!

Destination classes

Each Migration implementation needs to create a destination object - a subclass of MigrateDestination (or its subclass

Developing wizards for registering migrations

Migrate 2.6 introduces an API to assist in the development of step-by-step wizards for registering migration processes. By implementing a

Drush commands for Drupal 7's Migrate module

Using drush, individual migrations can be imported and then rolled back. Running processes can be cleanly interrupted, individual source

External references

People have applied the Migrate module in many different contexts, using it in different ways. Fortunately, some have taken the time to

Field mappings

Source fields are mapped to destination fields by making calls to $this->addFieldMapping() in your Migration class constructor. Field

Getting started with Migrate

Note: This documentation is for Drupal 7 contrib Migrate module, the Drupal 8 core Migrate API documentation can be found here.

Handler classes

Handlers are classes which enable you to add additional behavior to the processing of data being imported. These are usually used to support

Improving migration performance

Migrating large volumes of data can take considerable time - hours, or if you're migrating millions of objects, days. Shaving a few

Map classes

A key feature of the Migrate module is the tracking of relationships between source records and the Drupal objects that have been created

Migrate module FAQ

Migrate module architecture

The central class in the Migrate module - the one you'll spend most of your time dealing with - is the Migration class. You derive your own

Migration and group registration

Migrations and migration groups

Migration classes

The Migrate module provides an abstract class named Migration - in most cases, you'll do nearly all your work in extending this class. The

Source classes

The Migrate module uses classes derived from the abstract class MigrateSource to encapsulate source data to be imported. In a Migration

Why you should run migrations in Drush rather than the UI

If at all possible, you should execute your migrations using Drush rather than the UI for all but the smallest projects. To understand why,

Guide maintainers

frankcarey's picture