Drush 8 to Drush 9 Migration Path

August 22, 2019
By Aaron Meeuwsen,
Senior Developer

Drush is a way for developers to easily monitor, update, and execute various functions throughout a Drupal site instance. Currently, Drush 8 is the go-to version that most sites are using. Now, officially Drush 8 is not recommended to be used with any Drupal instance running core 8.4 or later. See the chart below: 

screen grab of the Drupal compatibility chart

Expanding on Drush is outside the scope of this post. However, if you would like more information about all the neat things Drush can do for you, please visit this link.

While this sounds quite negative on the surface, there have been many stating that Drush 8 is still working just fine for most uses. However, with the coming of Drupal 9, the upgrade to Drush 9 is inevitable. To put it simply, you will have to upgrade to Drush 9 eventually; even before upgrading to Drupal 9. Below we will discuss three important migration-specific cases to address when upgrading from Drush 8 to Drush 9.

Upgrading to Drush 9

When upgrading to Drush 9, there are some “gotchas” to watch out for in the context of migration definitions and commands to execute them. In this post, we will walk through three important factors you should address when upgrading. But first, we will take a quick look at migrations and where they are now in relation to Drupal 8.

With migrations now packaged up in Drupal 8 core, the new ability for developers and site editors to move content in and out of Drupal is nothing short of revolutionary. Developers now have the ability to easily create robust and extendible migration paths using only Drupal core. The updates to migrations in core were really to create a smooth upgrade path between versions; both Drupal 8 and other future releases. However, the real power of migrations lies in the ability to theoretically import any structured data into Drupal.

Now, migration itself is always a tricky subject when getting down to details. Relationships, field mappings, update contexts; all of these things contribute to how the migration is defined and data is used. Having an easy and extendable way of defining and processing all of these factors is what differentiates a great migration workflow from a satisfactory one. To that end, while defining them is an important part of the process, migrations would be useless without an easy way to execute and monitor them. This is where the very well-known Drupal developer tool Drush comes into play.

Now, let’s walk through the “gotchas” to look out for while upgrading. 

Executing Migrations with Drush 9 

The first change anyone will notice with Drush 9 is that you can no longer use the old commands such as drush mi cool_migration. Drush 9 has a different structure for defining migration and subsequently how to call them. There are no changes required to your migration YML files to solve this. The only requirement is to change the way we call migrations just a bit. So, the example above would now look like this drush migrate:import cool_migration. Not a huge change, but a necessary one to get your migrations called correctly. 

Migration Files Need Correct Names for No Warning 

While this change is nothing that will “break” your migration, it still does produce some scary looking and recurring errors when interacting with your migration. With Drush 8, there wasn’t a naming convention to follow when defining your migrations. The name of your migration YML file could be migration.cool_migration.yml while your migration machine name was super_cool_migration and Drush 8 was fine with that. However, for Drush 9 to not throw a warning error, you now have to match a substring of your migration file with the machine name of the migration. An example would be migration.cool_migration.yml with a machine name, cool_migration.

Drush 9 File Path

In Drush 9, the file path is different than Drush 8. This is a small change that can produce some developer migraines if not properly addressed. A migration can use structured data located in another file as its source. Previously in Drush 8 when defining this path, the system would begin its directory search in the module root. See below for an example of this file structure: 

screenshot of file structure for example

The file path for Drush 8 would be "/data/data.csv."

When executing a migration in Drush 9, the file path search now beings in the docroot of your project. Using the same file structure as above your new Drush 9 file path would be "modules/custom/cool_migrations/data/data.csv."

As you can see, this is a change that is required to be made if you want your migrations to execute successfully. 

Get Ready to Upgrade

The need to upgrade to Drush 9 will one day be required. Hopefully, you find these points useful and can use them to save you a few headaches when doing so. If any other major points come up that should be known to the community, this post will be updated. Thanks for reading!