Executing migrations

Last updated on
28 August 2021

This documentation needs work. See "Help improve this page" in the sidebar.

Importing migration YAML definitions

The contributed Migrate Plus module allows migration plugins to be implemented as configuration entities, allowing them to flexibly be loaded, modified, and saved. 

  • Make sure that core Migrate and contributed Migrate Plus modules are enabled.
  • Navigate to admin/config/development/configuration/single/import of your Drupal 8 site.
  • Select 'Migration' as the configuration type.
  • Paste your migration definition YAML to the configuration import form and click 'Import'.

Checking migration status

The contributed Migrate Tools provides drush migrate-status Drush command that you can execute on the command line of your server.

If you don't see the migration:

  • verify that you have enabled your custom module (if you are using a custom module that provides Migrate API source / process / destination plugins)
  • verify that your custom source / process / destination plugins are located in src/Plugin/migrate/source, src/Plugin/migrate/process, src/Plugin/migrate/destination directories
  • if you are using an SQL source plugin, verify that you have defined the source database connection in your settings.php or settings.local.php and that the database connection parameters are correct.

Executing the migration

Using Drush and Migrate Tools

The contributed Migrate Tools provides 'migrate-import' and 'migrate-rollback' Drush commands. The command below migrates 10 rows from a migration with id 'games' so that you can verify the results on your Drupal 8 site. If you wish to migrate all rows from the source, leave out the 'limit' argument.

drush migrate-import games --limit=10

Using Drush and Migrate Manifest

The contributed Migrate Manifest module allows you to run a group of migrations in a reproducible manner and in the correct order based on the migration dependencies. Usage examples are provided in the Upgrading to Drupal 8 handbook.

Rollback the migration

After you have executed the migration, verify the result on your Drupal 8 site. If you find out that you need to modify the migration a bit, you can roll back the migration with the 'migrate-rollback' Drush command. Also this Drush command is provided by the contributed Migrate Tools module.

drush migrate-rollback games

Executing the migration on schedule

The contributed module Migrate Scheduler provides a way to execute the migrations on a configurable schedule. It also provides options to execute the migrations with an --sync flag or an --update flag, or both.

Modifying the migration definition 

There are different ways how the already imported YAML format migration definitions can be updated.

Option 1

  • First export the current version of the migration definition at admin/config/development/configuration/single/export
  • Copy the migration definition to a text editor and modify it as needed
  • Import the modified migration definition at admin/config/development/configuration/single/import
  • After configuration refresh; refresh the migration record via its originating configuration.drush migrate-status

Option 2

  • It is possible to modify the configuration using the Drupal Console command line tool:
    drupal config:edit migrate_plus.migration.games
  • You will need to run drush cr to rebuild the cache before the import is executed again.
  • After configuration refresh; refresh the migration record via its originating configuration.drush migrate-status

Help improve this page

Page status: Needs work

You can: