The migrate_upgrade module provides drush support for performing upgrades from previous versions of Drupal to Drupal 8. It implements two drush commands:
- migrate-upgrade – performs a complete import of the source site’s congiuration
and content into the target Drupal 8 site. Optionally, with the –configure-only
flag, it may create migration configurations for such an import without actually
running them, to permit customization of the import process.
- migrate-upgrade-rollback – removes content and certain configuration
previously imported either by the migrate-upgrade command or by the core
The upgrade command requires a Drupal 6-style database URL of the source site’s database, and the location of the source site’s public files.
drush migrate-upgrade --legacy-db-url=mysql://user:[email protected]/d6db --legacy-root=http://example.com
The –legacy-root option may be either the domain of your existing Drupal site (with the public files pulled by HTTP), or a local file directory into which you have copied the files directory from your source site.
If your source site used a database prefix for all tables, you may specify the prefix with –legacy-db-prefix. Migration from sites with partial or mixed prefixing is not supported. Note that if the source site is stored in a Postgres schema, you must set the prefix to the schema with a period appended (e.g., –legacy-db-prefix=drupal.).
The migrate-upgrade command, like the core upgrade UI, is designed to be run on a freshly installed and empty Drupal 8 site (where the only site configuration that has been done is enabling any modules for which you wish to migrate data).
The rollback command has no arguments or options:
If it detects that an upgrade has been performed, either by migrate-upgrade or by the core UI, it removes all content imported via the migration process (it identifies the upgrade by the presence of the migrate_drupal_ui.performed state key). In addition, any configuration entites created by the migration process (such as content type and field definitions) are also removed. Because simple configuration settings (such as the site title) are generally modified rather than created by the upgrade process, and the original values are not preserved, those changes are not rolled back. To completely return to the previous state, you need to restore the site from backup, or reinstall a fresh empty site.
At the time of this release, tools have not yet been developed (along the lines of the migrate_d2d_ui module under Drupal 7) for customizing Drupal-to-Drupal migrations in Drupal 8. For now, the best option short of doing custom development is to use the –configure-only option on migrate-upgrade to replace the actual execution of the migrations with export of their configuration to configuration entities, which can then be modified as needed for a particular migration scenario. A suggested workflow:
- Install a fresh empty D8 site, enabling all modules for which you wish to migrate data.
- Run the drush migrate-upgrade command with the –configure-only option. This generates migration configuration entities in the D8 database (config table).
- Create a custom module containing only a .info.yml file (with dependencies on migrate_plus and migrate_drupal) and a config/install directory.
- Export your site configuration, e.g. drush cex –destination=/tmp/export
- Copy the migration configuration that was generated by migrate-upgrade into the custom module – be sure *not* to copy the default group configuration, which is defined by migrate_plus:
cp /tmp/export/migrate_plus.migration.* /tmp/export/migrate_plus.migration_group.migrate_*.yml migrate_custom/config/install/
- Look at that migrate_plus.migration_group.* file – you’ll see your database configuration captured there. In most cases, what you’ll want to do is define your database connection in settings.php with those credentials under the key that is configured there – you won’t want to commit the credentials to your git repo.
- Edit the generated .yml files to reflect your custom migration path.
- Reinstall D8, enable your custom module and migrate_tools, and proceed to work with your Drupal migrations as you would with any custom migration. Hint: you’ll probably want config_devel so you can edit .yml files in config/install and immediately test your changes.
Note that the configuration entities generated above need to be prefixed to avoid conflict with the core migration plugins they originated from. For example, by default the core d6_user plugin generates the upgrade_d6_user configuration entity. You may modify the ‘upgrade_’ prefix by providing a –migration-prefix option.