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
configuration 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
upgrade UI.

migrate-upgrade
===============
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:pw@127.0.0.1/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).

migrate-upgrade-rollback
========================

The rollback command has no arguments or options:

drush migrate-upgrade-rollback

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.

migrate-upgrade --configure-only
================================
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:

1. Install a fresh empty D8 site, enabling all modules for which you wish to
   migrate data.
2. Run the drush migrate-upgrade command with the --configure-only option. This
   generates migration configuration entities in the D8 database (config table).
3. Create a custom module containing only a .info.yml file (with dependencies on
   migrate_plus and migrate_drupal) and a config/install directory.
4. Export your site configuration, e.g. drush cex --destination=/tmp/export
5. 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/
6. 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.
7. Edit the generated .yml files to reflect your custom migration path.
8. 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.