Last updated March 24, 2014. Created by mikeryan on October 15, 2012.
Edited by Remon, cilefen, DanChadwick, peteruithoven. Log in to edit this page.

The Drupal-to-Drupal data migration module (migrate_d2d) extends the framework provided by the Migrate module to support migration of content and data from one Drupal installation to another. It understands the core schemas of Drupal 5, Drupal 6, and Drupal 7, as well as the contributed CCK module for versions 5 and 6.

At this time, migrate_d2d is a framework only, and requires implementing a custom module to register (and potentially override) the appropriate classes for your particular scenario. Down the road we expect to add a UI to enable at least basic migration scenarios to be done with no additional code.

Bundled with migrate_d2d is migrate_d2d_example, which demonstrates the basics of registering migration classes, as well as examples of overriding the classes to handle custom field mappings. Also see https://www.acquia.com/blog/drupal-drupal-data-migration-part-1-basics for a brief overview.

While the migrate_d2d_example is a good demonstration for the most basic migrations, an overall understanding of the underlying migrate module is extremely helpful. Time spent reading and studying the Migrate documentation will allow you to much more easily create your own custom migrations.

Class registration

The migrate_d2d classes are based on the Dynamic migration concept. Each migration class must be explicitly registered with an array of arguments, and you can register a class multiple times (with different machine names and different arguments to distinguish them). For example, you can register DrupalNode6Migration with one set of arguments to import articles, and another to import blog posts. Typically, you will have code in hook_flush_caches() to perform the registration (note that registering an already-registered class will have no effect, other than updating it with any argument changes).

Common class arguments

Classes have names of the form Drupal{object}{version}Migration, where {object} is the type of Drupal 7 entity to create (User, Node, etc.) and {version} is the Drupal version number of the source system (5, 6, or 7). Thus, to import users from Drupal 6, you would use DrupalUser6Migration.

All migrate_d2d migration classes require the following arguments to be specified (see the child pages for details on each specific migration class):

  • machine_name: The unique machine name to assign to this migration.
  • source_version: The Drupal version of the source database (5, 6, or 7).
  • description: A brief description of the migration (e.g. "Import legacy article nodes into D7 blog nodes").
  • source_connection: Connection key for the DatabaseConnection holding the source Drupal installation. See http://drupal.org/node/1014558 for information on defining the connection.

Optional arguments that apply to all migrate_d2d migration classes:

  • source_database: As an alternative to defining your connection in settings.php, you can add the database array as an argument to your migrations.
  • group_name: The name of the migration group to hold your migrations (defaults to 'default').
  • dependencies: Migrations that must be run before this migration. Some common dependency relationships are handled by more specific arguments, but this allows you to add custom dependencies.
  • soft_dependencies: Migrations that should be run before this migration. These dependencies are not enforced, but help determine the order that migrations are listed and run.
  • format_mappings: An array mapping format IDs or machine names in the source database to format machine names in the destination. For example, in your Drupal 6 installation you may have had a format named Markdown with the ID 5 (there were no machine names in Drupal 6), while in Drupal 7 the format named Markdown Format has the machine name markdown. Thus, you could pass as an argument 'format_mappings' => array(5 => 'markdown'). Note that default mappings based on name are automatically generated - thus, if you have formats named Filtered HTML on both sides, they will be properly mapped without any work on your part.
  • source_options: An array to be passed as options to the MigrateSourceSQL constructor. The defaults are map_joinable FALSE, cache_counts TRUE, and cache_key derived from the machine name.
  • version_class: There is a helper class for each Drupal version (5, 6, or 7) used to do things like figure out what fields are available on entities. You can override this class to customize this behavior - if so, pass your class name in this variable.

A best practice is to define an array containing those arguments that will not change for any of your migrations, then append to it the class-specific arguments you need. An example of a common arguments array:

<?php
$common_arguments
= array(
 
'source_version' => 6,
 
'group' => 'example',
 
'source_connection' => 'legacy',
 
'source_database' => array(
   
'driver' => 'mysql',
   
'database' => 'drupal6_db',
   
'username' => 'legacy', // Ideally this user has readonly access
    // Best practice: use a variable (defined by setting $conf in settings.php, or
    // with drush vset) for the password rather than exposing it in the code.
   
'password' => variable_get('example_migrate_password', ''),
   
'host' => '12.34.56.78',
   
'prefix' => '',
  ),
 
'format_mappings' => array(
   
'5' => 'markdown',
  ),
);
?>

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.