Welcome, migrators!

This site is to help you get up and running with Drupal 8's migration system.

It is based on a presentation we have given at many conferences. Original notes and slides.


Core: migrate, migrate_drupal, migrate_upgrade

Contrib: migrate_tools, migrate_source_csv, migrate_upgrade

Console: drush (drupal console also has some features)

Fully Automated?!

If migrating from D6 & D7 the /upgrade page is available after installing the modules. It will bring over config and content with no options for overriding.

Settings.php for core migrate:
$databases['migrate']['default'] = array (
   'database' => 'cooks_legacy',
   'username' => 'root',
   'password' => 'my-secret-pw',
   'prefix' => '', 
   'host' => 'db',
   'port' => '3306',
   'namespace' => 'Drupal\Core\Database\Driver\mysql',
   'driver' => 'mysql',

If using migrate_upgrade, subsititute 'migrate' with 'upgrade'. If fully custom, call it what you want!

Commands in migrate_tools:
  • drush migrate-status (ms)
  • drush migrate-import $migration (mi)
  • drush migrate-stop $migration (mst)
  • drush migrate-reset-status $migration (mrs)
  • drush migrate-rollback $migration (mr)

To check status go to /admin/structure/migrate or open a new terminal and run "drush ms".

You can kill a dead process using drush migrate-reset-status and simply restart it with no loss.

Generated Migrations (from Drupal 6 & 7)

The following tiles describe connecting to a Drupal 6, Drupal 7, or perhaps other "known" migration sources.

Generate migrations based on source site:
drush migrate-upgrade \
--legacy-db-url=mysql://user:password@server/db \
--legacy-root=http://example.com \

--legacy-db-url is not necessary if you crated 'upgrade' db in settings.php.

--legacy-root is OPTIONAL if you don't want to download the files right now.

If you don't want to "drush config-export" to modify anything:

drush migrate-import --all

Importing DB with Generated config from another site...

You will probably get an error message that the legacy DB does not exist by that name (unless all of your team works with the same db settings).

Fix: drush config-export, edit migrate_plus.migration_group.migrate_drupal_7.yml (or whatever your group file is called), and then drush config-import.

Exporting generated config
  • You can create a module with config/install folder;
  • copy the output files from drush config-export into it;
  • but you must remove uuid and add custom group, or wipe the past imports completely.
  • Consider if you need a module or if config-export and config-import suffice.

Custom Migrations (from a file, in this example)

The following tiles describe connecting to a unique source and defining a migration from scratch.

Migration Group File (yaml)

  • Contains DB connect info
  • Constants that will be re-used in migrations

Migration Config File (yaml)

  • Metadata
  • Source Plugin(s)
  • Process Plugins(s)
  • Desintation Plugins
  • Dependencies

Custom Plugins

The following tiles describe connecting to a unique source and defining a migration from scratch.