Upgrading to Drupal 8 using Drush

So, perhaps you've been reading Upgrading to Drupal 8 using the UI and thinking "hey, what about us cool kids who use Drush for everything?". Or, maybe you just know drush is better than a UI for running long processes like migrations. Well, this blog post is for you... We do have drush commands for running and rolling back upgrades, currently in the migrate_upgrade module (but which should land in Drush itself by Drupal's 8.1 release at the latest). First off, for preparing a D8 site to run the upgrade process, we're just going to give the tl;dr version here - see the UI post for more context. ~/Sites/d8$ # Install Drupal using the minimal profile ~/Sites/d8$ drush si minimal --account-name=admin --account-pass=admin --db-url=mysql://user:pass@127.0.0.1/d8 -y You are about to DROP all tables in your 'd8' database. Do you want to continue? (y/n): y Starting Drupal installation. This takes a while. Consider using the --notify global option. Installation complete. User name: admin User password: admin Congratulations, you installed Drupal! ~/Sites/d8$ # Enable the D8 modules corresponding to each source module you want upgraded. ~/Sites/d8$ drush en -y book,comment,block_content,menu_link_content,menu_ui,path,search,taxonomy The following extensions will be enabled: book, comment, block_content, menu_link_content, menu_ui, path, search, taxonomy, link Do you really want to continue? (y/n): y ... ~/Sites/d8$ # Don't forget the rest of the field types. ~/Sites/d8$ drush en -y datetime,image,options The following extensions will be enabled: datetime, image, options Do you really want to continue? (y/n): y ... ~/Sites/d8$ # Get the Drupal Upgrade (machine name migrate_upgrade, for historical reasons) module. ~/Sites/d8$ drush dl migrate_upgrade Project migrate_upgrade (8.x-1.x) downloaded to /Users/mryan/Sites/d8//modules/contrib/migrate_upgrade. ~/Sites/d8$ # Enable it! ~/Sites/d8$ drush en -y migrate_upgrade The following extensions will be enabled: migrate_upgrade, migrate_drupal, migrate Do you really want to continue? (y/n): y migrate was enabled successfully. migrate_drupal was enabled successfully. migrate_upgrade was enabled successfully. The Drupal Upgrade module has been enabled. Proceed to the upgrade form. ~/Sites/d8$ # Make sure it'll look nice when we're done. ~/Sites/d8/modules/contrib/migrate_upgrade$ drush en -y bartik The following extensions will be enabled: bartik Do you really want to continue? (y/n): y bartik was enabled successfully. ~/Sites/d8$ # Back up your database first! ~/Sites/d8$ drush sql-dump >/tmp/d8-pre-upgrade.sql

Running the upgrade

OK, you've now got a vanilla Drupal 8 site ready to accept your Drupal 6 or Drupal 7 site data. It's now simply a matter of running the drush migrate-upgrade command, pointing it at your legacy database (or a copy thereof - it is not recommended to run directly against your production database) and at the source for your files (which may be scraped from your live website, or copied from a local directory): ~/Sites/d8$ drush migrate-upgrade --legacy-db-url=mysql://user:pass@127.0.0.1/d6_site_db --legacy-root=http://mikeryan.name Upgrading d6_book_settings Upgrading d6_date_formats Upgrading d6_dblog_settings Upgrading d6_file_settings Upgrading d6_imagecache_presets Upgrading d6_search_settings Upgrading d6_system_cron Upgrading d6_system_date Upgrading d6_system_file Upgrading d6_system_image ... Upgrading d6_node_revision__story Upgrading d6_node_revision__todo Upgrading d6_node_setting_promote Upgrading d6_node_setting_status Upgrading d6_node_setting_sticky Upgrading d6_taxonomy_vocabulary Upgrading d6_taxonomy_term Upgrading d6_vocabulary_field Upgrading d6_vocabulary_field_instance Upgrading d6_vocabulary_entity_display Upgrading d6_vocabulary_entity_form_display Upgrading d6_term_node__1 Upgrading d6_term_node__2 Upgrading d6_term_node_revision__1 Upgrading d6_term_node_revision__2 Upgrading d6_user_contact_settings Now, wasn't that easier than clicking through a bunch of forms? One other option to the migrate-upgrade command worth mentioning is --configure-only. The upgrade process has two distinct stages:

1. Configuration: the database credentials are used to read and analyze the source database. Given the modules enabled on the source side and on the destination side, the relevant migration templates are configured and saved as runnable migration configuration entities.
2. Import: The import() operation is run for the migration entities configured in the first stage.

So, if you pass the --configure-only option, only the configuration is performed and you're left with all the migrations you need, ready to run. The advantage of that is that you can use the migrate_tools module (part of the migrate_plus project, about which more in a future blog post) to selectively run the migrations: ~/Sites/d8$ drush migrate-status Group: default                Status Total Imported Unprocessed Last imported block_content_type            Idle   1     0        0 d6_book_settings              Idle   1     0        0 d6_date_formats               Idle   3     0        0 ... d6_upload                     Idle   2     0        0 d6_upload_entity_display      Idle   5     0        0 d6_upload_entity_form_display Idle   5     0        0 d6_user_contact_settings      Idle   683   0        0 ~/Sites/d8$ drush migrate-import d6_date_formats Processed 3 items (3 created, 0 updated, 0 failed, 0 ignored) - done with 'd6_upload' Finally, if you choose to go back and try the upgrade again from scratch, you can rollback the full upgrade (as explained in the UI post, simple configuration changes will not be restored): ~/Sites/d8$ drush migrate-upgrade-rollback All migrations tagged as 'Drupal' will be rolled back. Are you sure? (y/n): y Rolling back d6_user_contact_settings Rolling back d6_upload_entity_form_display Rolling back d6_upload_entity_display Rolling back d6_upload ... Rolling back d6_file_settings Rolling back d6_dblog_settings Rolling back d6_date_formats Rolling back d6_book_settings Rolling back block_content_type Alternatively, to be sure you are returning completely to square one, you can restore your backup: ~/Sites/d8$ mysql -u user -p d8 </tmp/d8-pre-upgrade.sql

How'd it go?

This is one part of the UI post worth repeating - the upgrade path in Drupal core for 8.0 is experimental, and we need your feedback to tighten it up and make it fully supported for 8.1. If you ran into any problems in upgrading your site, or have suggestions for improving the process, please share them:

1. If your problem or suggestion is specifically about the drush commands, please open an issue in the Drupal Upgrade issue queue (being sure to check if it's already been reported, of course).
2. If you had error messages while the upgrade process was running, or something was not imported correctly into your site, please open an issue with the "migration system" component in the Drupal core issue queue (again, checking for previous reports).

If you're not sure where to report the issue, just pick one and don't sweat it - we'll move it if necessary. Thanks!