Migration Tips and Tricks

Posted on Wed, 04/09/2014 - 14:42

The Migrate module is, hands down, the defacto way to migrate content in Drupal. The only knock against it, is the learning curve. All good things come to those who take the time and learn it.

I have summarized some tips and tricks I have learned. Thank you to Mike Ryan and Alex Ward for helping me get up to speed.

Drupal's Migrate module is a code-centric approach to migration. As such, I highly recommend leveraging Drush during development. Here are some tips I have used, some of which require Drush to be installed.


1. drush mreg

Quick and dirty way to register new Migration classes after you have already installed your migration.

2. drush ms

This is the fastest way to review the current state of migration classes. It also tells you if a class is registered or not (you either did not register or you did not correctly define the class in the info or migration.inc files).

3. drush mi --limit=5

The "mi" command is short for migrate import. Some imports can be rather large. While debugging, it's useful to use the limit flag with a number of records as a parameter to run a fixed sample of records. This can save a ton of time in identifying issues, while not waiting for an entire migration to complete.

4. prepareRow($row)

Each migration class has a prepareRow function that is extremely powerful. This enables you to alter row data before the mappings occur. This is also a critical place for debugging. Throwing in a drush_print_r($row) is an effective way to see mapping values for each record. Lastly, if you need to filter out rows, you can throw conditions in here and return FALSE to ignore specific rows.

5. drush mr

Even seasoned vets must iterate on migration classes during development. You will frequently be importing and rolling back. Leverage this command to rollback after running the import.

6. Data analysis

One key concept to this is mapping. You must map the existing data structures to new data structures (fields and content types). You will likely run into issues where things do not cleanly map to the new destination. Get questions in front of your client ahead of the development and as soon as possible. This can proactively help identify issues in scope.

7. Use of migrate version 2.6-rc1

An absolute must. A lot of polish has been applied to this version. Save yourself some hassle and just start with this version.

8. Use of linkchecker module

Migrations can be difficult to verify. You will likely be altering paths for images and links within the HTML of imported content. In doing so, download and enable the linkchecker module. Configure it to scan all content types found in your migration. Run the migration, and run cron until all links have been checked.

9. Use of the scanner module

This module enables you to verify the contents of content. If you alter HTML within prepareRow, you may want to spot check content for given conditions. But, spot checking large migrations are nearly impossible. Use of the scanner module enables a developer to check conditions within the imported content, instead of manual and error prone checks. It does have the ability to replace, but this should exist within your migration class to be applied in subsequent migration iterations.

10. drush mmsg

Due to the iterative nature of developing a migration, it's critical to see any output generated by a migration class. Use this command to review any output generated from a migration class. This helps with debugging fine grain issues you may run into, especially if customizations are made within the prepareRow function.



Best of luck in your future migrations! They are often not fun. At least Mike Ryan and the other migrate contributors have given us a tool that helps the cause.