Upgrading Drupal 7 to Drupal 9

Drupal 9 is far better than Drupal 7 and Drupal 7 is coming to the end of its life. There're many topics mentioned about that, so this blog will not explain why we need to migrate.

This blog is showing how we migrate a complex website from Drupal 7 to Drupal 9 completely without any problem, without any business stuck, and without any missing content, …
The sample project for this blog is https://apexembdesigns.com.

We're allowed by the client to use this website as a sample to showcase how to migrate:

  • Original version: This website was built by Drupal 7 in 2010 (by another Company)
  • Over 10 years: the owner wanted to upgrade to Drupal 9
  • Some information about this website:
    • - 104 nodes
    • - 13,912 products
    • - 407,142 users
    • - 3,773,586 orders
    • - 6,967,976 file license
    • - 131 taxonomy terms
    • - 14 taxonomy vocabularies
    • - 208,201 files
    • - 25,061 wishlists
    • - 222,143 wishlist items
    • - 4,458 votingapi_result
    • - 3,759 votingapi_vote
    • - 965,386 webform submissions
    • - 966,848 alias
    • - 11,425 redirect items
  • Requirement
    • - Don't break their business (this system receives thousands of orders per day)
    • - Keep all data 100% the same as it’s in the Drupal 7 site, with no missing pieces of content
    • - Keep all pages, blogs
    • - Keep all contents, user, data
    • - Keep all process
    • - Keep all orders
    • - Keep all URL aliases
    • - Improve some functions
    • - ...

Step 1: Review the project thoroughly

This step helps us understand almost (almost, can’t everything) what we have in this website from DB, source code, modules, theme, pages, contents, public files, and private files, … Depending on our experience we can see 90%, 80%, 60% of the project. The higher the percentage we can see in this step, the more sure we can complete the project.

Step 2: Rebuild the data structure

Following the D7 data structure, we build a data structure, content types, taxonomy, user, and entities, ... for D9. Normally, we will do the same, however, in some cases, we need to improve to have a better structure in Drupal 9.

Step 3: Rebuild the theme

Create a theme, create and style manually for all template pages

Step 4: Rebuild modules & functions

Almost modules in d7 are available in d9. However, sometimes we face bad cases, for example in this project, the file license module is not good to use, so we need to code a new module to handle that function.

Step 5: Migrate data

This is the most difficult and important step. There’re many modules and guides on the internet but unluckily, all of them are unhelpful for this size of the web. To solve this problem, we coded a custom module that helps us to handle all situations of data from small (hundreds of content) to very big (tens/hundreds of millions of contents) and this module is adapted and improved by each project. When it’s flexible enough, we’ll release a contrib module.

The basic idea of the module is: the migration data handles in five steps:

  • Installing: we install a migration module in Drupal 9 to handle the migration, and a custom module for Drupal 7 to respond to all data in the Drupal 7 site as the APIs
  • Fetching: The migration module in Drupal 9 will call one by one API in Drupal 7 to get all data, saving it to the migration mapping table
  • Parsing: Load all entry in the migration mapping table and create the new appropriate entity entry in Drupal 9, this step only migrate the non-relationship fields (text, URL, boolean, number, …), save the newly created entity key (entity id, entity type, bundle) to keep track for the next step
  • Linking: Load all entries in the migration mapping table, get all relationship fields (taxonomy term, entity reference, uid, files, image, media, alias, redirect, …), get the appropriate new entity, and set this field. After Step 3, all entities have existed and all related fields are linkable.
  • Last updating (at the released date, after Step 6: Test below): Because the size of data is significant, we need a few days to migrate but the live site is still running, data is still being added, and we can’t ask clients to stop the website to wait for, we can only do it when the live site is still running. But when everything is ready, the website is ready to go live, we can ask them to move the old site to maintenance mode in 1 day, and in that time, we will migrate the last time for the new/updated data only, and this process runs very quickly. After that, we will have everything from the Drupal 7  site in the Drupal 9 version, we can replace it now.

Step 6: Test

This is a very important step too. To release a project not only solve what we can see but also all the points we can't see that are found by the Tester and the Client. Depending on the complexity of the project, this step should be about 20% to 50% of the total time frame.

Step 7: Go live

After all, we have the completed project, all functions run well, all bugs are found and fixed, and the new website will replace the old one.

Step 8: Maintain

This is the time that we need to solve some remaining issues that were not found in the Testing step.

Step 9: Develop and deploy new requirements

This is the happiest time in this project because updating functions, and deploying new features on Drupal 9 is wonderful, much much better than what Drupal 7 was.

Here is the end of the guide. Hope with the 9 steps above, you can imagine how a migration project works, what is the migration process, and what to notice.

Thank you for reading!