Upgrade using the migration user interface

Last updated on
23 November 2016

The first step to migrating is to prepare your site for the upgrade.

Next, verify that you are using the latest version of Drupal 8 by checking the latest release for Drupal and checking your current version by visiting the status report page in your installation (/admin/reports/status). The migration tools are in the process of development, so in order to ensure you have the most recent migration updates, keep up to date with Drupal core.

Make sure these modules are enabled on your Drupal 8 site: "Migrate," "Migrate Drupal," and "Migrate Drupal UI."

Next, visit the /upgrade page. When you do you will see this screen:

Migrate Upgrade starting page

Note: If you do not see the page above, but instead see a 404 page, please verify you have enabled the 'Migrate Drupal UI' module.

Press continue to configure your migration source (see screenshot below). Enter the database credentials and path of your Drupal 6 or 7 site's files (as explained previously), and press Review upgrade. If your Drupal 6 or Drupal 7 site uses a database prefix, be sure to expand the Advanced options and provide that prefix.

Drupal Upgrade database credentials page

If the database credentials are correct, the upgrade review page will list the sources and destinations existing or missing based on modules present on the source site. The page provides a summary of the upgrade paths found and missing and then details the missing ones first:

Missing updates on the Drupal Upgrade review page

You cannot do anything directly on this page to fix these missing migrations. Some of them may just be missing implementations that need to be developed while others signify modules not installed on the destination site. In this example, the book module is enabled on the source site but was not installed in the preparation step on the destination site, therefore, it is reported missing.

The available migrations are listed below this list and are collapsed by default. When uncollapsed, this list allows you to review what will end up where on the new site. For example, this shows that the block module from the source site is migrated to two modules on Drupal 8. There is absolutely nothing to do about these, the list is purely informational.

Available updates on the Drupal Upgrade review page

This is the final page before the actual execution of the upgrade, so this is the final chance to hit Cancel. Once you press the Perform upgrade button, the process is started. Depending on the size and types of content/configuration on the source site, the upgrade may take a very long time (possibly hours for a bigger data set). Due to password encryption, user accounts take particularly long to import. Continuous feedback is provided along the way with both progress information and errors encountered:

Progress messages of Drupal Upgrade

New messages show up at the top of the page, while old ones disappear at the bottom as the process goes on. However, all of these messages are logged and can be reviewed later. Once the process is finished, you are directed to the site's frontpage with messages summarizing the results:

Results of the Drupal Upgrade process

Here you have a chance to review the messages that were logged and inspect any errors found. The module uses the built-in logging system of Drupal, so in a default setup you can just review the logs stored in the database, which is where the link leads to:

Logs from the Drupal Upgrade process

You can filter the list of messages to show notices (used for positive feedback) or errors (used for reporting problems found in the migration). If something breaks, you've either found a bug (in which case, check the issue queue or contact the Migration team) or your data set is too large (in which case, try running the upgrade with Drush).