04 - November - 2016

Migrating Ixis.co.uk from Drupal 6 to Drupal 8

Post by Andy R Andy R

This is a summary of the process we undertook to migrate the Ixis site from Drupal 6 to Drupal 8 including some of the issues we came across.

Caveat: the migration was run around May/June this year and there is a lot of work currently going into Migrate. There are likely to be better approaches now.

Using the migrate modules

There is good documentation surrounding the the Drupal upgrade process on drupal.org.

As there is no upgrade path from Drupal 6 to Drupal 8 as there is for previous Drupal versions, to migrate the Drupal 6 site to Drupal 8 we needed to use the migrate_upgrade module. This module provides a drush command that takes an entire Drupal 6 site, both site configuration and content and migrates it to Drupal 8.

This can be done by:

drush migrate-upgrade --legacy-db-url=mysql://user:pass@12.34.56.78/d6db --legacy-root=http://myd6site.com

Unfortunately, migrating the entire site did not suit our use case as we wanted to build the site in Drupal 8, removing some of the legacy setup along the way and migrate most (but not all) of the content. 

For example, we recreated our content types in Drupal 8, using different field names and to make use of the Paragraphs module. 

If we used the upgrade path provided by migrate we would end up with the same content types as Drupal 6.

We also did not want to migrate all the content. We had content types in use that were no longer relevant to the business so we did not want to migrate the configuration for the them, nor the nodes.

We considered not using migrate_upgrade at all. However, this would mean creating the entire migration from scratch.

As there was some of the configuration we did want, taxonomy vocabularies and menus for example, our approach was to try and migrate the content and only some of the configuration. 

This meant taking the migration configuration entities generated by migrate_upgrade and picking the migration configuration apart to separate site configuration migration and content migration.

To only generate the migration configuration entities and not actually run the migration the

--configure-only

option can be passed to the migrate-upgrade command shown earlier.

The process

The process of unpicking configuration and content was complex. The content depends heavily on configuration being migrated first. For example, when migrating a node with a body field, the text format that exists in the Drupal 6 site needs to be migrated to Drupal 8 first.

We began un-picking the configuration we did not need migrating by seeing if the config already existed on our rebuilt Drupal 8 site. 

If it already existed, we updated the migration config to remove it. If it did not exist and we were happy with the D6 version, we allowed migrate to import it.

For example, as we did not want all text formats from the Drupal 6 site we needed to modify the configuration entities. If a body field existed with a text format we did not want in the Drupal 8 site we had to modify the migration configuration to map that text format to the new one on the new site. We also had to remove the configuration entity that would create the text format from being recreated during the migration process.

This was a laborious process. The cycle of alter config -> import -> test -> rollback -> alter config was time consuming meaning our progress was slow. 

As the Drupal 8 site was still changing as we were doing this, it made the migration configuration a moving target.

Plugins

To achieve the goal of only importing some content types we remove the config d6_node__<content type>.yml file. This worked fine, those nodes were not imported.

However, this had a knock on effect of other migrations throwing errors. For example, the 'd6_upload' migration would fail due to it finding files that were referenced by the nodes we no longer import.

To help us, we wrote a simple plugin that exclude these files from the d6_upload migration.
 

-- modules/custom/ixis_migrate_from_d6/src/Plugin/migrate/source/d6/FilteredUpload.php --

<?php

/**
 * @file
 * Contains \Drupal\ixis_migrate_from_d6\Plugin\migrate\source\d6\FilteredUpload.
 */

namespace Drupal\ixis_migrate_from_d6\Plugin\migrate\source\d6;

use Drupal\file\Plugin\migrate\source\d6\Upload;

/**
 * Drupal 6 upload source from database, with filters.
 *
 * @MigrateSource(
 *   id = "d6_filtered_upload",
 *   source_provider = "upload"
 * )
 */
class FilteredUpload extends Upload {

  /**
   * {@inheritdoc}
   */
  public function query() {
    $query = parent::query();
    $query->condition(
      "n.type",
      $this->configuration['exclude_node_type'],
      "NOT IN"
    );

    return $query;
  }

}

-- <config dir>/migrate_plus.migration.d6_upload.yml --

source:
  plugin: d6_filtered_upload
  exclude_node_type:
    - webform
    - story

This created a new source plugin called "d6_filtered_upload" that took a "exclude_node_type" configuration option. This was used to alter the original query from the Upload class to exclude the node types specified.

Considerations

Migrate is experimental. This means there is no guarantee there will be no breaks in backward compatibility. For example, updating the site from 8.0 to 8.1 broke our existing migration config until we could rename all our exported config.

As of Drupal 8.2 migrate will not migrate user or node reference fields. There has been a lot of work towards this in https://www.drupal.org/node/2447727 but is not here yet.

Summary

In hindsight the approach taken proved problematic. Although migrate_upgrade gave us a starting point, it was difficult to unpick config and content, especially as we were not migrating some of the content nor all of the site config.

If we were to do this again, we would:

  • most likely build the migration from scratch so we could just migrate the content we needed. 
  • avoid upgrading the Drupal 8 version whilst we were still trying to configure migrate to avoid any BC breaks.

Having said all that, if you want to migrate your Drupal 6 site to Drupal 8 in its entirety, then we have had good experiences with migrate_upgrade doing just that.
 

Andy R

Andy R

Senior Developer

Comments

Everything will work perfectly for Drupal 8 at the same time Drupal 9 gets released..

Someone

Add new comment

Share this article

Our thoughts

Let's work together

Get in touch and find out how we can empower your organisation.
Back to top