Drupal-to-Drupal Migrations (Drupal 7 Upgrade)

In this course, Drupal-to-Drupal Migrations, you will learn how to upgrade an existing Drupal 6 or 7 site to the latest version of Drupal. We’ll cover how to plan your Drupal-to-Drupal migration, compare paths you can take in authoring an upgrade migration, and how to choose a path that is right for your situation. Along the way, we’ll show you lots of migration tips and tricks.

In Drupal, there’s no direct upgrade from Drupal 6 or 7 to the latest version of Drupal. Instead, an upgrade to the latest version of Drupal requires you to migrate your site and files from a previous Drupal version (version 7 or lower) to the latest version of Drupal (or Drupal 8 and higher). The core migrate system aims to make this process as easy as possible. Because upgrades are built using the Migrate API, you’ll be authoring custom migration YAML files and plugins.

We also recommend you spend time learning about the underlying Migrate API in our related course, Explore Source, Process, and Destination Migrate API Plugins.

And if you're just getting started learning about migrating to Drupal, make sure you've walked through our Migrating to Drupal Essentials course first. This will give you a foundation in the concepts, terminology, and modules used in the migration ecosystem.

Tutorials in this course
More information

Before you begin a Drupal 6 or 7 (source) to Drupal 9 or 10 (destination) migration there are a number of things you should consider. Taking the time to plan your migration will help to ensure that you're successful. In this tutorial we'll take a high-level look at:

  • Evaluating your existing Drupal 6/7 site for migration feasibility
  • Preparing your source Drupal 6/7 site for a migration
  • Preparing the destination Drupal site you're migrating to

By the end of this tutorial you should be ready to start assessing the feasibility of performing a successful migration, and begin making a migration plan.

More information

Because current versions of Drupal are so much different from older versions like Drupal 7 upgrading to the latest version requires creating a new site using the latest version of Drupal and then migrating your old site's content and configuration into it.

There is no one right way to tackle a Drupal-to-Drupal migration. Instead, it's like walking down a path and coming to a fork in the trail and then choosing a direction over and over and over. Since every site is different, every path to a finished migration will be different, too. I know nobody wants to hear it, but every migration is its own unique adventure. Every successful migration will require its own custom code, weird shell scripts, and detailed lists of the exact order of things. But that doesn't mean there's no plan to follow.

A successful migration charts a course through the maze, while leveraging existing tools and experience to help find the shortest route and the right path at each fork--with minimal backtracking due to wrong choices.

In this tutorial we'll:

  • Look at what makes a Drupal-to-Drupal migration (a major version upgrade) so tricky, and how to think about performing one
  • Define 3 high-level approaches to performing a Drupal-to-Drupal migration
  • Get a better idea of what the migration work entails, so you go into it with a proper mental model.

By the end of this tutorial you should be able to explain the different approaches to performing a Drupal-to-Drupal migration in broad strokes, and have a better picture of the work that will be involved.

More information

Before you can migrate your Drupal 7 site to the latest version of Drupal you'll need to be able to build the features that make up the current site. Part of this is evaluating all the modules you've got installed, figuring out what you're using them for, and if there's a version that's compatible with the latest version of Drupal along with a migration path.

I usually make a spreadsheet for this. But any list of the modules you’re currently using that allows you to keep track of how you plan to update them will work. You also want to keep track of where you are in the process of figuring that all out. Because it’s likely you’ll have some modules for which the path is clear, and others where it’s pretty murky and requires more in-depth research to find a path forward. Having a list means you can break that up into tasks, and ensure you’re not missing something. It'll also help you define when your migration is done as well as any final quality assurance (QA) tasks.

In this tutorial we'll:

  • Start a list of the modules that make up our current site.
  • Point to some tools that can help speed up the process of evaluating a module's readiness.
  • Provide a set of questions that you can ask about each module you're using as part of your planning process.

By the end of this tutorial you should have a list of all the modules you're currently using, and some tools you can use to help you figure out how to move forward with each one.

More information

When preparing to migrate from an older version of Drupal (Drupal 7 or previous) to the latest version of Drupal (Drupal 8 or later) you'll need to determine if the contributed modules you use are ready to go. The Upgrade Status module can give you a list of all the modules installed on your site, and information about the availability of a latest Drupal version. It's not perfect, and will still require some manual research for some modules, but it is a great start towards helping you plan for your migration.

In this tutorial we'll:

  • Install the Upgrade Status module and use it to generate a status report
  • Review the generated report
  • Talk about using the Contrib Tracker project, and other methods for getting more details about the status of upgrades for any module

By the end of this tutorial you should be able to evaluate all the installed modules on your existing Drupal site and determine the status of a module release that is compatible with the latest version of Drupal.

More information

It's not uncommon to patch, or customize, contributed modules during the lifetime of a site. It's important to know if you've done so when planning for a migration since you'll want to be sure that you don't lose any customizations when you start using an updated version of a module.

In this tutorial we will walk through using the Hacked! module to check for any alterations to your Drupal code base.

More information

If you want to be able to say you're done with your Drupal-to-Drupal migration, first you have to be able to define "done". And part of that is doing a content analysis and inventory. Performing a content analysis and inventory will help you ensure that you don't miss any fields or important records. It also gives you an opportunity to spend some time thinking about the overall information architecture of your site. You're already going to be doing a lot of work to migrate your content, so deciding to shuffle things a bit now might not add any significant extra time. Additionally, the latest Drupal (as of Drupal 10) is a different platform than either Drupal 6 or 7, and as such, there are some new best practices and new ways of doing things that might not have been available before.

In this tutorial we'll:

  • Provide a set of questions you can ask yourself about the content of your current site to kick-start your analysis.
  • Give an example of how we create a content type inventory in a spreadsheet and use that to help define "done" for our projects.

By the end of this tutorial you should be able to get started analyzing the content and content types of your existing site in order to start planning for your Drupal-to-Drupal migration.

More information

The Drupal-to-Drupal migration system is still a work in progress. As such, there are a few things that simply don't work, and a few others that still have kinks to be ironed out. In this tutorial, we'll look at some of the common hang-ups that we've encountered, the status of resolving those issues, and what your options are in the meantime.

More information

The Migrate Drupal UI module allows you to execute a migration from older versions of Drupal to the latest version of Drupal. In this tutorial we'll:

  • Run a full Drupal 6 to latest-Drupal (Drupal 8 or 9) Migration from the UI
  • Explore the user interface as it exists
  • Understand how we can deal with the output from our migration
More information

In this tutorial we will run a site migration using Drush, and understand how to deal with any failures that occur.

More information

Drupal core provides support for migrating data from Drupal 6 or 7. The templates provided in core migrate your data in a very specific way. They attempt to copy things verbatim whenever possible. However, you may wish to alter this for your migrations. In this tutorial we are going to explore the various ways that you can alter the existing Drupal-to-Drupal migrations to meet your needs.

More information

Why use Migrate Upgrade and Migrate Plus? The short answer is: because it'll save you from having to type out a bunch of YAML by scaffolding a migration for you.

The contributed Migrate Plus and Migrate Upgrade modules are commonly used to aid in the process of performing a Drupal-to-Drupal migration. The combination of the two makes it easier to customize the configuration of individual migrations on a per-project basis by allowing you to edit each individual migrations configuration using the same mechanics that you would to write a custom migration.

It's not the only approach to making these changes, but for many people (including us), it's the most efficient way.

In this tutorial we'll:

  • Get a more in-depth look at the role of the Migrate Plus and Migrate Upgrade modules
  • Discuss the use cases for using them as part of a Drupal-to-Drupal migration

By the end of this tutorial you should be able to explain what both the Migrate Plus and Migrate Upgrade modules are used for.

More information

One method of creating a custom Drupal-to-Drupal migration involves using the Migrate Upgrade module to generate a set of migration configuration entities that you can use as a starting point. Even if you're not going to use the generated output in the end, this is still an informative exercise as it allows you to see examples of various migration paths.

In this tutorial we'll:

  • Use the Migrate Upgrade module's Drush commands to import Drupal core's migration templates
  • Examine the generated configuration entities
  • Use the Migrate Tools module's Drush commands to view a list of the individual migrations that make up our Drupal-to-Drupal migration

By the end of this tutorial, you should be able to use the Migrate Upgrade module to generate the migrations that Drupal core would use to migrate content, list those migrations, and inspect them individually.

More information

If you want to modify the Drupal-to-Drupal migrations created by Migrate Upgrade you'll need to export the Migrate Plus configuration entities, convert the ones you want to customize to standard migration .yml files, and put them into a custom module. Then, you can make edits the YAML definition of the migration, and keep your customizations in Git.

We recommend creating a new module to house the code that makes up your custom Drupal-to-Drupal migration.

In this tutorial we'll:

  • Create a new module
  • Export the migration configuration entities generated by drush migrate-upgrade as YAML files
  • Copy the files that represent the migrations we're interested in into our new module
  • Customize the copied files

By the end of this tutorial you should have a new module that contains the starting migration YAML files for your custom migration.

More information

As part of creating a custom Drupal-to-Drupal migration we want to limit the set of users that are migrated from our source site into our destination Drupal site. In this tutorial we'll:

  • Extend the existing source plugin
  • Alter the query that's used to select users from our source site
  • Update our user migration to use the new source plugin

By the end of this tutorial you should be able to override the core source plugins used when migrating from prior versions of Drupal in order to gain more control over exactly what is migrated.

Drupal 8, 9, and 10
More information

Every row returned, from every source, during the execution of a migration is passed through hook_migrate_prepare_row() and hook_migrate_MIGRATION_ID_prepare_row(). Using these two hooks we can augment our migration in a variety of different ways.

In this tutorial we'll:

  • Discuss the use case for hook_migrate_prepare_row()
  • Implement hook_migrate_prepare_row() and use it to skip all but a select list of fields during the field migration
  • Implement hook_migrate_MIGRATION_ID_prepare_row() and use it to skip all but a select list of node types

By the end of this tutorial you should have a better understanding of when hook_migrate_prepare_row() might be useful when writing your own migration, as well as how to skip rows in a migration based on conditional logic.

This course appears in the following guides:
Module Development
Upgrade from Drupal 7 or import custom data using Drupal's Migrate API.

Learn to Migrate to Drupal