Migrate Upgrade
Provides Drush commands for performing complete upgrades from Drupal 6 or Drupal 7 to Drupal 8+ sites.
migrate_upgrade
Install
composer require 'drupal/migrate_upgrade:^4.0'
composer require 'drupal/migrate_upgrade:8.x-3.2'
Overview
Migrate Upgrade is a powerful migration module that enables automated upgrades from older Drupal versions (6 and 7) to modern Drupal sites (8, 9, 10, 11+). Unlike the core Drupal upgrade UI which operates through a web interface, this module provides comprehensive Drush command-line tools for performing migrations, giving administrators greater control and flexibility over the upgrade process.
The module integrates with Drupal's core migration framework and the Migrate Plus module to generate and execute migrations. It can either run migrations immediately to perform a complete site upgrade, or generate migration configuration entities that can be customized before execution. This configure-only workflow is particularly valuable for complex migrations that require custom field mappings or data transformations.
Key capabilities include support for multiple database connection methods (direct URL or settings.php key), file migration with both HTTP and local file path support, database prefix handling for prefixed Drupal installations, and a complete rollback feature to undo imported content and configuration.
Features
- Performs complete content and configuration migration from Drupal 6 or 7 to Drupal 8+
- Supports both direct database URL connections and pre-configured database keys in settings.php
- Handles file migrations via HTTP from remote sites or local file directories
- Generate-only mode exports migrations as migrate_plus configuration entities for customization
- Customizable migration ID prefixes to prevent conflicts with core migration plugins
- Complete rollback functionality to remove imported content and created configuration entities
- Automatic derivative migration expansion for content type-specific migrations
- Debug mode with detailed ID map message logging
- Integration with Drush simulate mode for dry-run testing
Use Cases
Complete Site Upgrade from Drupal 7
Perform a full migration of content, users, configuration, and files from a Drupal 7 site to Drupal 10. Install a fresh Drupal 10 site, enable all modules you want to migrate data into, then run: drush migrate-upgrade --legacy-db-url='mysql://user:pass@host/d7db' --legacy-root=https://old-site.com
Customized Migration Workflow
Generate migration configurations for review and customization before execution. Run with --configure-only, export configurations to a custom module, modify YAML files to adjust field mappings or add process plugins, then use migrate_tools to execute: drush migrate-upgrade --legacy-db-url='mysql://user:pass@host/d7db' --configure-only --migration-prefix=custom_
Migration with Pre-configured Database Connection
When the legacy database connection is already defined in settings.php (useful for environments where credentials shouldn't be passed via command line), use the database key: drush migrate-upgrade --legacy-db-key=legacy_drupal --legacy-root=/mnt/legacy_files
Migration Rollback After Testing
After running a test migration on a staging environment, completely remove all imported content and configuration entities to start fresh: drush migrate-upgrade-rollback
Drupal 6 to Drupal 10 Upgrade with Prefixed Database
Migrate from a Drupal 6 site that uses table prefixes: drush migrate-upgrade --legacy-db-url='mysql://user:pass@host/d6db' --legacy-db-prefix='drupal_' --legacy-root=https://old-site.com
Tips
- Always run upgrades on a freshly installed target site with only the modules you need enabled
- Use --configure-only for complex migrations that need customization before execution
- The config_devel module is helpful when iterating on migration YAML configurations
- Test migrations on a staging environment before running on production
- Back up your target site before running migrations, even though rollback is available
- Enable all destination modules before running the upgrade to ensure proper migration discovery
- Use the --debug option to see detailed progress and error information during migrations
- Migration IDs are prefixed with 'upgrade_' by default to avoid conflicts with core migration plugins
Technical Details
Drush Commands 2
drush migrate:upgrade
Performs a complete import of the source Drupal 6 or 7 site's configuration and content into the target Drupal 8+ site. Can also be used with --configure-only to generate migration configuration entities without executing them.
drush migrate:upgrade-rollback
Rolls back and removes all content and configuration entities that were imported by a previous upgrade operation. Identifies upgrades by the migrate_drupal_ui.performed state key. Note: Simple configuration changes (like site title) are not rolled back as original values are not preserved.
Troubleshooting 6
The command requires database connection information. Provide either --legacy-db-url with a full database URL, or --legacy-db-key referencing a connection defined in settings.php ($databases array).
Ensure --legacy-root is correctly set. For remote sites, use the full URL (https://example.com). For local files, use the absolute file system path to the Drupal root. Files should be accessible at the standard Drupal file locations (sites/default/files).
Run migrate-upgrade on a freshly installed Drupal site. If content already exists, use migrate-upgrade-rollback first, or reinstall the site.
Increase PHP memory limit. Consider running migrations in batches using --configure-only to generate configurations, then using migrate_tools with --limit option.
The configurations are stored in the database, not as files. Use drush cex to export them, or check the migrate_plus.migration.* entries in the config table.
When using PostgreSQL schemas, set --legacy-db-prefix to the schema name with a trailing period, e.g., --legacy-db-prefix='myschema.'
Security Notes 3
- Database credentials passed via --legacy-db-url are visible in process lists and shell history. Use --legacy-db-key with settings.php for production environments.
- When exporting migrations with --configure-only, database credentials may be stored in migration group configuration. Review and remove credentials before committing to version control.
- The module requires access to the legacy database which may contain sensitive user information. Ensure proper access controls are in place.