Guideline for Upgrading Drupal 8 To Drupal 9 Step by Step

Upgrading CMS is a necessary activity to make when there are new updates of the website or application that platform providers are offering. However, with each new feature or system update, it is more than just a “click”  to upgrade the current CMS version, as the process can be much more complicated. Therefore, in this article, Kyanon Digital will share how to re-systemize the process when upgrading a certain CMS system, especially about gaining better understanding through factual case study for the Upgrade from Drupal 8 to Drupal 9.

1. Instructions for upgrading the CMS system
1.1 When it is necessary to upgrade CMS system

At start, people usually have a few questions:

  • Is the upgrading process of the CMS system very complicated, time-consuming, and a drain on resources?
  • When should we upgrade? How often should it be for an upgrade?
  • When upgrading, are we capable of being in control of the process ?
  • Is there a way to make the upgrade process easier?

Obviously, upgrading a system or a software is a compulsory requirement. Every system needs an upgrade. It is because all products and versions of software are upgraded by the administering organizations, whether it is open source or enterprise license. For enterprise license software, the seller will be responsible for the upgrade.

Why is it necessary to upgrade CMS?

Guideline For Upgrading Drupal 8 To Drupal 9 - Step By Step 1


  • Firstly, upgrading ensures your system is always up to date, and all bugs are patched.
  • Secondly, upgrading ensures safety of the system.

The latest version of software normally has new features after patches. One important thing is that when you regularly upgrade to the latest version, it will make the next one easier.

Distinguish Updating and Upgrading:

Update small versions, which can be understood as patches, security bug fixes, and small features updates.It can be understood as a major upgrade, which can change most of the old software architecture, such as the structure of the code or the database. Upgrading is more difficult and time-consuming than Updating. Regular Updates will make Upgrades easier. Usually, the upgrade will follow the life cycle of the product and framework, so it is necessary to include this plan at the operation and maintenance stage of the project. For example, you can read about Drupal here
1.2. CMS system upgrade stages

Guideline For Upgrading Drupal 8 To Drupal 9 - Step By Step 2

1.2.1. Preparation stage

The preparation phrase has a vital role and consumes a considerable amount of time. Developers usually have confusion about this stage thinking that it is only about preparing the steps to deploy in stage 2 (the Upgrade phase). In stage 1, it also includes the operating preparation of the system during the upgrade, reaching an agreement with the customer, and a suitable time arrangement with other teams. Because it is not only an upgrade of one CMS, but it can also be related to the network system, server system, OS license, database version, third-party integration, etc.

  • Plan preparation: based on the project’s scale, the degree of “customize”, automation, source code normalization, features testing, etc., and remember to make the script according to the “best practice guideline” of the corresponding CMS.
  • Consider the caveats between the current version and the target version: the changes of API and data structure.

Guideline For Upgrading Drupal 8 To Drupal 9 - Step By Step 3

  • Examine the entire current environment in which CMS is operating: It takes a professional mindset and coordination of multiple development departments, sysadmins, etc. to see the risks. For example, determining which versions of OS server and database server is not the CMS development team’s job. Inspecting integrated softwares’ versions from third-party: search system, composer, npm, shell management, etc. It is recommended to deploy a testing version to determine the actual running time, and prepare for possible risks.
  • Create backup and restore versions: Check in advance whether the upgraded environment is able to run on the customer’s server or not. These 2 versions can be used to compare with future upgrades.
  • Upgrade structure: Determine whether the upgrade structure is manual or tool application.
  • System synchronization: It is necessary to synchronize the system during the testing phase and the upgrade stage because there will be changes in log files, etc.
1.2.2. Upgrading stage

It normally includes main works such as:

  • CORE
  • API
  • Database
  • Automation Script
  • Deployment Environment
1.2.3. Confirmation & Testing stage

Dealing arising errors: Tests of Front-end, authorization, every function, logs and status, etc.

1.2.4. Deployment stage

It is necessary to determine the implementation plan, and there are 2 options as follows:

Freeze content

Hot content

Stop the running server (freeze the server for a while), backup the database, restore to a new environment, then upgrade the database with the upgrade code. Finally, restore that database to production.Upgrade source code and files directly on live production, then run upgrade live database.

At this point, it is necessary to have a team ready for bug fixes right away if something goes wrong.

1.3. Here are some advices for developers

Guideline For Upgrading Drupal 8 To Drupal 9 - Step By Step 4

You must always update the system regularly, patches need to be updated immediately with a specific work plan according to the product life cycle. This will keep the system and security up to date, making future upgrades easier.

You need to be prepared for the worst case scenario where unexpected errors can occur.

You need to have a full features checklist for each upgrade version.

2. Instructions for upgrading Drupal website from Drupal 8 to Drupal 9

The following is an example of the number of websites using Drupal from version 6.x and above, which utilize the “Update status” module that will be updated by Drupal in the table. For each week starting on the given day, the metric will show the number of websites that are using specific versions of Drupal.

According to a statistic by, in December 2021 there are about 830,000 websites in need of upgrading to Drupal 9 – the latest version of Drupal.

Guideline For Upgrading Drupal 8 To Drupal 9 - Step By Step 5

2.2. Upgrading CMS from Drupal 8 to Drupal 9 process (collected from Kyanon Digital’s cases)

Guideline For Upgrading Drupal 8 To Drupal 9 - Step By Step 6

Phase 1: Review (1-2 days)

B1: Receive requests from customers: database, demo.

B2: Deploy the site on your local, there will be a site that works similar to the product site.

B3: Use the support tool to generate reports to check modules, there are changes in API from Drupal 8 to Drupal 9.

Phase 2: Upgrade (1 week)

During the preparation phase, the Kyanon Digital team builds an environment to perform the upgrade using the corresponding docker container. The advantage of using docker is that it will create environments with the closest configuration to the customer’s environment.

2.2.1. Upgrade modules
  • Automatic upgrade:

Guideline For Upgrading Drupal 8 To Drupal 9 - Step By Step 7

B1: Check the version of each module in turn listed in the aggregate file on, change to the latest compatible and most stable version for each module.

B2: Once done, run “composer install” to upgrade modules.

  • Manual upgrade:



1. Examine patches and apply them.1. Fix the errors that arise after upgrading.
2. Create a patch if the latest version is not available.2. Fix compatible theme errors with the upgrade version.
3. Move the developer module to the require-dev environment. 

Guideline For Upgrading Drupal 8 To Drupal 9 - Step By Step 8

Some special cases:

  • The latest version of the module does not support Drupal 9.
  • The module cannot be upgraded to the latest version because another module requires a lower version.
2.2.2. Update database

Guideline For Upgrading Drupal 8 To Drupal 9 - Step By Step 9

Some common errors: When deleting the requested modules by customers, there will be an error if you delete it before updating, because it still exists in the database of that module.

It is necessary to follow the process: delete the module after updating the database.

2.2.3. Import configuration

Guideline For Upgrading Drupal 8 To Drupal 9 - Step By Step 10

When updating the database, the configuration of the modules will change, so they must be exported and imported again.

Depending on customers’ requirements, you will know if you need to re-sync the configs or not. You can use some Drupal tools to check and compare the configs stored in the current database when updating, which will result in knowing the differences of the version before and after the update. We need to review these different points to know what changes have been made on the website so that we can control the changes on the web after the update.

Guideline For Upgrading Drupal 8 To Drupal 9 - Step By Step 11

Phase 3: Testing (1-2 weeks)

B1: Test the basic operations on the site.

B2: Request Smoke test from customer to test.

B3: Test the requirements from the developer team.

Phase 4: Maintenance (2-3 weeks)

After the release has operated and the QC has finished testing, return it to the client to deploy preview. It is possible that there will be more bugs found, so this stage will take a lot of time to fix errors that arise. Finally, we hand over the product to the customer and answer related questions if there are any.

Kyanon Digital hopes that you have gained valuable knowledge when participating in Drupal upgrade projects and especially when upgrading Drupal websites from Drupal 8 to Drupal 9. If you have any questions, please do not hesitate to contact Kyanon Digital for the fastest consultation.

5/5 - (1 vote)