Migrate Tools
Provides UI and Drush commands for running and managing Drupal migrations.
migrate_tools
Install
composer require 'drupal/migrate_tools:^6.1'
Overview
Migrate Tools is an essential companion module for Drupal's core Migrate API. It provides both a web-based administrative interface and powerful Drush commands for managing migration processes.
The module enables site administrators to view migration status, execute imports and rollbacks, monitor progress, and inspect migration messages—all through an intuitive UI or command line. It works seamlessly with the Migrate Plus module to provide entity-based migration management with migration groups.
Key capabilities include batch processing support for large migrations, sync functionality to keep source and destination in alignment, shared configuration for DRY migration definitions, and comprehensive logging with progress indicators.
Features
- Web UI for viewing and managing migration groups and individual migrations with status, counts, and last import timestamps
- Drush commands for all migration operations including import, rollback, stop, reset, disable, and status checking
- Batch processing support for running large migrations through the web UI without timeout issues
- Sync functionality to automatically delete destination records that no longer exist in the source data
- Progress bar display during Drush command execution with real-time status updates
- Migration message viewer showing errors, warnings, and notices from migration runs
- Source, process, and destination pipeline inspection pages for debugging migrations
- Shared configuration system allowing common migration settings to be reused across multiple migrations
- Dependency tree visualization showing migration relationships and execution order
- ID list filtering to import or rollback specific source records
Use Cases
Migrating content from Drupal 7 to Drupal 10
Use Migrate Tools with Migrate Upgrade to generate migration configurations, then use Drush commands to import content. Run 'drush migrate:status' to see available migrations, then 'drush migrate:import --all' to execute them. Use '--update' flag for incremental updates.
Importing data from CSV files
Combined with Migrate Source CSV module, create migration configurations pointing to CSV files. Use the execute form in the UI to run imports with batch processing for large files. Monitor progress and check messages for any issues.
Syncing content between environments
Use the '--sync' option with migrate:import to keep destination in sync with source. This deletes destination items that no longer exist in source, useful for keeping a staging site synchronized with production data.
Debugging migration issues
Use the admin UI to inspect source fields, process pipelines, and destination configuration. Check the Messages tab for errors and warnings. Use 'drush migrate:messages' with '--format=csv' to export issues for analysis.
Running partial migrations during development
Use '--limit' to process only a subset of items for testing. Use '--idlist' to import specific records. Use '--feedback' to monitor progress on large migrations.
Sharing migration configuration across multiple migrations
Create shared configuration in MODULE.migrate_shared_configuration.yml or in migrate_shared_configuration/*.yml files. Reference shared config using 'include' key in migrations to DRY up common source, process, or destination settings.
Tips
- Use 'drush migrate:reset-status' when a migration is stuck in 'Importing' or 'Rolling back' status
- The '--sync' option is powerful but destructive - it will delete destination content not in source
- Use '--continue-on-failure' in automated scripts to prevent one failed migration from stopping the entire batch
- The UI execute form uses batch processing which is better for large migrations than direct PHP execution
- Install Migrate Plus module for full UI functionality - without it, only Drush commands are available
- Use '--skip-progress-bar' in CI/CD environments where interactive output isn't supported
- Check migration dependencies with 'drush migrate:tree' before running imports to understand execution order
- The '--idlist-delimiter' option allows custom delimiters when source IDs contain colons
Technical Details
Admin Pages 10
/admin/structure/migrate
Lists all migration groups defined in the system. Shows group label, machine name, description, and source type. Provides operations to list migrations within each group, edit group settings, or delete groups.
/admin/structure/migrate/add
Form to create a new migration group. Migration groups help organize related migrations together and can share common configuration.
/admin/structure/migrate/manage/{migration_group}
Form to edit an existing migration group's settings including label, description, and source type.
/admin/structure/migrate/manage/{migration_group}/migrations
Lists all migrations within a specific migration group. Shows migration status, total source count, imported count, unprocessed count, message count, and last import timestamp.
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}
Displays overview information for a specific migration including group assignment, description, and dependencies (both required and optional).
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/source
Displays the source plugin configuration and available source fields for the migration. Shows the source query/configuration and a table of field machine names with descriptions.
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/process
Displays the process pipeline configuration showing how source fields are mapped and transformed to destination fields.
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/destination
Displays destination plugin information including the destination type and available destination fields.
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/execute
Form to execute migration operations including import, rollback, stop, and reset. Provides options for updating existing items, ignoring dependencies, limiting items, and filtering by ID list.
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/messages
Displays paginated list of messages generated during migration import. Shows source IDs, severity level, message text, destination ID, and row status.
Permissions 1
Hooks 2
hook_migration_plugins_alter
Allows modules to alter migration plugin definitions. Migrate Tools uses this to process 'include' directives for shared configuration.
hook_migrate_prepare_row
Allows modules to alter a row before processing. Migrate Tools uses this to track source IDs for sync functionality.
Drush Commands 9
drush migrate:status
Lists all migrations with their current status including group, migration ID, status, total items, imported count, unprocessed count, message count, and last import timestamp.
drush migrate:import
Performs one or more migration import operations. Imports unprocessed source records into Drupal destination entities.
drush migrate:rollback
Rolls back (deletes) destination entities created by one or more migrations.
drush migrate:stop
Cleanly stops an active migration operation, allowing the current item to complete before halting.
drush migrate:reset-status
Resets a migration's status to Idle. Use when a migration is stuck in Importing or Rolling Back status.
drush migrate:disable
Disables a migration, preventing it from being executed until re-enabled.
drush migrate:messages
Displays messages (errors, warnings, notices) associated with a migration import.
drush migrate:fields-source
Lists all available source fields for a migration, showing machine name and description.
drush migrate:tree
Displays a dependency tree showing which migrations depend on others.