Drupal has been in the content management game for over two decades. That is a long period of time and in that time span the CMS has accomplished a lot. It’s community of over a million Drupalists is just one part of it. With 20 years gone, Drupal is still running strong and it’s latest update is proof of that. 

Yes, in the June of 2020, amidst the pandemic, Drupal 9 was launched and it was my only sunshine at that time and I am sure many of my Drupal friends would agree with me. Drupal 9 can be deemed as one of the best offerings of Drupal, not there were many that were anything but great.

Job done easy: Drupal 9 upgrade

The latest version meant we had to take it on, why be comfortable with the past when the present can offer more comfort, right? However, the mammoth task that was the Drupal 8 upgrade, you must remember that, made many of us apprehensive and rightfully so. And that is where we were surprised, pleasantly might I add, by Drupal. 

“Easiest upgrade in a decade.”

This is how the Drupal 9 upgrade is being described and it is because you won’t have to replatform your site, you’d only be updating. It's like taking a connecting flight from London to Paris rather than leaving the airport and taking a train from the station. Connecting flights are easy.

Considering the fact that Drupal 9 is not a migration, the upgrade is a breeze. With the addition of new features like Olivero and Claro, being built and stabilised respectively, the new versions of Drupal 9 will become all the more appealing and a release can be expected half yearly much like Drupal 8. So, can we afford to sit back and not take the step towards upgrading our Drupal sites. The fact the Drupal 7 and Drupal 8’s end-of-life has been decided has given us all the more reason to make the upgrade. 

To help you in finding the answer to the popular question of “How to upgrade Drupal 9?”, here I am with an all inclusive checklist for this massive step you are about to take. So, let’s begin.

Is the upgrade different for Drupal 7 and Drupal 8?

This is one of the most commonly asked questions for Drupal 9 upgrade. There are still a lot of Drupal sites that are still operating on the 7th version, so it is understandable to want to know whether ‘the easiest upgrade of the decade' is applicable to them or is it different. 

Drupal 9 upgrade is different for Drupal 7 and 8 sites. This is mainly because Drupal 8 was a whole other ballgame than Drupal 7, while Drupal 9 is just a new and improved version of Drupal 8 with no deprecated APIs. Therefore, the upgrading process was bound to be different.

Let’s see how. 

Drupal 8 to Drupal 9 

Support for Drupal 8 will end on 2nd November, 2021, it will receive patch releases, but there won’t be any major updates in its feature simply because we have Drupal 9. Therefore, upgrading to the newer version is the better option. 

To upgrade from Drupal 8 to Drupal 9, 

• You would have to see that all your projects are Drupal 9 compatible; 
• You would have to see that your codebase is free of deprecated APIs; 
• And then all you would have to do is run update.php. 

It sounds simple enough, right? That is because it is. Of course, you would have to perform some more steps than these three and there would be a number of tools that you would have to use for them. However, it is these three steps that are essentially the crux of upgrading from Drupal 8 onto 9.

Drupal 7 to Drupal 9

Drupal 7’s support is said to end on 28th November, 2022. Although your D7 site has quite some time ahead of it, you still have to start thinking about the upgrade as the process is not as easy as the D8 to D9 upgrade. 

You can take two routes here; 

• You can first update to Drupal 8, avail functionality from all the modules that are yet to come in Drupal 9 and then take the easy route of upgrading to Drupal 9; 
• Or you can directly upgrade to Drupal 9 and skip the 8th version. This would be ideal because your upgrade would have a much longer lifespan.

For the upgrade from Drupal 7, you would need three modules; 

• The Migration Module Suite; 
• Upgrade Status; 
• And Drupal Module Upgrader. 

These three do everything from data and content migrations and checking the availability of modules to scanning them and updating them for the upgrade. 

So yes, the Drupal 9 upgrade from Drupal 7 and 8 is different, simply because they are very different versions of the CMS. 

Now that we have this notion clarified, let’s move on to all the nitty-gritty details of the upgrade.  

What tools would you need for the Drupal 9 upgrade?

Can you cook without the right ingredients? Can you make the perfect lasagna without the melt-in-the-mouth pasta? I know you know the answer to these two questions and that’s a big fat no. 

Therefore, the incredible journey towards the Drupal 9 experience has to start by talking about the tool you would need for it, the ingredients that’ll make the upgrade all the more appetising. I’ll stop with the cooking analogy now and come to the point. There are two mandatory tools that you will be needing.

Upgrade Status 

Upgrade Status is a module that ll but prepares your site for the upcoming upgrade you are planning to execute. It is a pretty versatile module that does all the grunt work required before making the leap to D9. 

• Your site has to be the latest version of Drupal, that is Drupal 8.8 or 8.9, so the first thing this module does is inspects whether you are on that version, if not, it’ll tell you to update.
• Your system needs to meet Drupal 9’s set requirements for the upgrade to go on smoothly, so the next thing it does is check if you meet them.
• Your contributed projects also need to be updated and be compatible with Drupal 9. If they are Drupal 8 compatible, there is a high chance they’ll be for Drupal 9. So, Upgrade Status works with Update Status to ensure every project is in sync.
• Your site needs to be compatible with Drupal 9 in other ways as well, so that is also checked and verified through phpstan.
• Your system’s integration drush is also taken care of here.
• Your system might have deprecated APIs, Upgrade Status finds, although there are any fixes provided; for that you'll need another tool.

Upgrade Status’ enchantment doesn’t end here, there is more to this module yet. 

• I’ve told you that it prepares your Drupal 8 site, but it also gives you the leeway for downloading it with and without the Composer. 
• It is also available in Drupal 7 and this version would help you in preparation for the Drupal 9 as well as Drupal 8 upgrade, if that is what you want. 
• Now, the most alluring part, once you’ll upgrade to Drupal 9, it’ll start preparing you for the Drupal 10 upgrade! Yes, you read it right, Drupal 10 launch is in the works and you can be ready for that when it happens with this module.

Deprecation Check

Remember I mentioned deprecated APIs above, well, there are more than APIs that can be deprecated and that needs your attention before you start creating the upgrade environment for your site. That is why, Deprecation Checking and Correction Tools become a necessity.  

All in all, there are five tools for your help. 

• The first one is an IDE or code editor, which comprehends deprecation to kickstart the process. 
• Then there is the Drupal-check, this one performs a PHP run and let’s you know whether deprecated code is used and where.
• Third is the Upgrade Status I talked about above, which essentially scans your entire system and finds deprecated code for you. 
• The Drupal.org Testing System also supports deprecation inspection.
• Finally, the Upgrade Rector Contributed Project provides a solution for all of the checking done above and that too in an automated manner.

What are the environment requirements for Drupal 9?

When you are roasting the perfect chicken, the temperature in the oven has to be just right, the timing has to be just right and the flavours have to be just right to make it come out all juicy and succulent. I know I have started with the cooking analogy again, but this is the best comparison I could think of. 

Like that perfect roast chicken, Drupal 9 also needs just the right environment from you and your system to make it work. And this involves; 

Web Servers

Drupal 9 can be run using two different web servers and you need to have the latest versions of these two.

• For nginx, you have to have the version 0.7.x or above; 
• And for Apache, it has to be at least 2.4.7.

PHP 

PHP is the language Drupal is built on, of course you must know that. What you may not know is that you need PHP 7.3 for operating Drupal 9. The latest version 9.1.0 supports PHP 8.

Database and Hosting Structures 

Drupal 9 has specific requirements for its backend database as well as its hosts. These are; 

• Version 5.7.8+ for MuSQL or Percona; 
• Version 10.3.7+ for MariaDB;
• Version 3.26+ for SQLite; 
• Version 10 for PostgreSQL; 

And if you are planning to use Drush to build your interfaces, go for version 10, since only that is compatible with Drupal 9.

Have you prioritised the update of the core codebase?

Drupal 8 was the last major release before Drupal 9. Like any Drupal version, there are a number of minor releases being launched and you must keep up with them. If you have done so, your core codebase would be up-to-date and you’d be all set for the upgrade. 

One of the Drupal 9 upgrade requirements is that your site be updated to Drupal 8.8 or 8.9 for you to be prepared for the easiest upgrade of the decade. 

What happens if you are on a version older than 8.8?

What’ll happen is the upgrade won’t go through. Now you might ask why? I’ll give you an analogy, can you skip a few grades and land from 6th grade directly to high school? Even if you could, would you say that getting the hang of the classes you’ll have be quite arduous? It most definitely will be. So, like you can’t skip grades and you can’t skip the minor releases of Drupal 8 before going on to Drupal. Because Drupal 8.9 and Drupal 9 are somewhat similar the upgrade is a breeze, however, Drupal 8.4 and 9 do not share that kind of similarity and you might need to upgrade fast. 

From upgrades in PHP to core modules, from themes to contributed modules and from path aliases and database, almost every aspect requires updating to be compatible with Drupal 9. And only Drupal 8.8 and 8.9 have that level of API compatibility. 

How to upgrade if you have a Drupal version that precedes 8.7? 

For a version older than Drupal 8.7, you would have to perform some small code changes and database updates that are not very complex. An update to the latest version of the core would be required, and this would make the database and contributed modules ready for the 9 upgrade.

You can use Upgrade Status to ensure that all of what you just did is compatible with Drupal 9 or not. 

Then you’ll have to check for deprecated code, like we discussed two sections above. Thereafter, you become ready to update your core codebase to Drupal.

How to upgrade if you have a Drupal version that succeeds 8.8?

If you are already on Drupal 8.8, there isn’t much you have to do in order to prepare yourself. The only task to perform is running the Upgrade Status and checking compatibility. 

There is one more thing that you will have to do. And that is what your existing site is based upon because that will decide how the actual upgrade will flow. 

Your site could be based on Composer or it could be based on Tarball. Make sure you keep that in mind before starting the upgrade, as both work on different upgrade mechanisms. While the former has its own list of steps to follow, the latter is upgraded using Drush.

What about updating the custom code?

After upgrading the core codebase, you would have to pay close attention to your custom code. There is a high chance that your project will have custom modules and themes, these mean a custom code would also there and it is your responsibility to update it. 

You wouldn’t need new tools and techniques to help you here. 

• Upgrade Status will scan all the projects for custom code deprecations; 
• Upgrade Rector will fix any minor deprecations by itself. 

Updating the custom code is not that big a task, so it is often neglected and overlooked. However, it is important enough to hamper the entire upgrade. So, don’t skip it.

Can the contributed projects be neglected?

If you have taken care of the core and custom projects, you can’t think about leaving the contributed project without any attention. So, updating them is the next agenda on the Drupal 9 upgrade checklist. 

The reason for updating the contributed projects is the same as the core and custom projects, to check the compatibility of the projects with Drupal 9. And you must know by now, since I am repeating it for what feels like the 100th time, Upgrade Status will help you in the compatibility check.

You must know that even though a module is Drupal 9 compatible, there is the off chance that it can be a version of a major release that’ll bring API changes along with it. You have to be mindful of these modules because they can be detrimental to your site’s health. API changes that you are not prepared for can’t be efficacious by any means.

But what if a module is not Drupal 9 compatible?

There are, of course, not many of them, however there are some and you must know how to handle them. You can do any of these two things in this scenario.

• Creating, you can create a custom code to update it;  
• Or waiting, you can wait to see if it gets updated by the time you are ready for the final upgrade;  

What about the contributed modules with patches, do they need attention?

There are situations where you may want to update a contributed module, but an update is not in the picture, rather you have patches available and sometimes, not even that. What would you do? Pay attention to the patches, that is what.

Usually if a patch is available for a module, Upgrade Status would inform you about that and you can implement it. 

Then there is the scenario, when a contributed module has neither an update and nor a patch. For such an instance, the combination of Upgrade Status and Upgrade Rector will have you sorted. You can also check Drupal’s Contributed Modules Guidelines to help you further. 

Have you examined your content and field types thoroughly?

Auditing for site building is a must. Adding fields and customisations in Drupal is quite easy, anyone can do it. This is both good and bad. Good because anyone can do it leading to less dependence on developers, bad because anyone can do it meaning there might be redundant field types and outdated content. And in this step, you check for just that. 

• Check and eliminate fields that were created for a once-in-a-lifetime event; don’t let them sit and waste away.
• Remember those content types you created to add content later, well, you haven’t done that yet, so they have to go as well.
• Update the help text; this might seem trivial to you, but being someone who relied on that piece of text to perform all my initial duties instead of pinging my manager every minute, trust me, it is important. If it is outdated, it is useless and why would you want something useless on your upgraded Drupal 9 site?

Customisations are only great until they don’t start bloating your site causing regression. You do not want that, so don’t just keep all your focus on the code, modules and themes, give some time to the content as well.

How do you become sure that your upgrade is successful?

You will execute the upgrade to make your site better than it already is, that should be the aim, right? However, despite you doing everything to the T, there is a chance that you may go in regression. Your upgrade may be doing everything that it is supposed to, but still your site’s performance can be slower than it was. 

Noone wants that scenario to become their reality, so how do you avoid that? How do you ensure that the upgrade is successful? There is certainly a way to ensure that and that’s through testing.

When you perform tests, you get to know what is truly happening with your site. Where you went wrong and what you did right won’t be hidden under a veil. For instance, performing a test to check the administrative and editorial working of the site is ideal. On paper, everything may appear sound, but in reality your editors could be struggling to make even the smallest of edits. And it is only through testing that you’ll be able to find that out. 

You can start at a smaller level with a hello world test and gradually scale up to examine the major aspects of the upgrade. 

Another thing that’ll help you in making the upgrade a success is going slow. Yes, upgrading to Drupal 9 is deemed as the easiest update of the decade, but it is still a huge task to take on. Just the sheer number of modules that wild require updating can become overwhelming, so go slow, update a few modules at one time. This is the chances of errors would be slim and the chances of success would be quite high. 

The Bottom Line 

Drupalists from across the globe had been awaiting the release of Drupal 9 for a long time, now that it is here, there is nothing holding us back from taking the upgrade leap. If I am to be honest, I’d say that I was fearful of the upgrade process. However, when Dries Buytaert say that one of the fundamental issues to address in the Drupal 9 release was the ease of installation, you cannot do anything but believe him. That’s what we should do.