20 Tips for Drupal Database Migrations

So there I was, happily finishing a security update on my Drupal 7 site, when I realized that one of my favorite modules — the Group Module — was no longer receiving updates. As I observed the menacing reddish-pink hue of the module’s security warning message, I was reminded of the inevitable: Drupal 7 would be losing community support in November 2022, and for some modules, support was already waning.

So right then and there, I decided that it was high time to get started with migrating my site, and such was the beginning of my foray into the universe of Drupal website migrations.

While migrating a Drupal site from D8 to D9 is seen as a rather straightforward endeavor — you may hear it described in some cases as a large security update — migrating from D7 to D8 or D9 is no small thing due to how different D7 is from its more advanced counterparts. And whether you are new to Drupal or a seasoned Drupal veteran, the migration process, which comprises both a database migration and oftentimes a new site build, can be a completely new mountain to climb.

If you are looking to migrate a Drupal 7 site to Drupal 8 or 9 soon and would like some guidance on making a plan, here are a few tips I gleaned on the database migration aspect from my own experiences. While the tips that follow are based on my experiences migrating a Drupal 7 site’s database to Drupal 9 through the web browser, I do allude to other, more involved methods towards the end.

General Tips

1. Study the documentation. To prepare, I studied Drupal’s Upgrade Using Web Browser guide, and referred to this resource often during the migration. The guide provided a helpful walkthrough of the process with screenshots of the key stages. Note that this particular guide is best for relatively simple sites, and other approaches may be better suited to complex migrations.

2. In most cases, migrate directly to Drupal 9. Because Drupal 8 loses support in November 2021, you would not be able to stay with it for long at this point. And Drupal 9 is very similar to Drupal 8 - just more streamlined without the deprecated modules and APIs that some Drupal 8 sites may allow. While migrating from D8 to D9 is less of a challenge than migrating from D7 to D8, it can still be arduous if your D8 site ends up containing some modules that are not ready for D9. So migrating directly to D9 can potentially save you time and cost.

3. Try migrating locally with Lando. Lando is a free open-source command-line tool for setting up a range of dev environments. It is built on top of Docker tech, and if you download it, you will end up downloading Docker as well if you do not already have it. When used with Drupal, Lando spins off your database and sets up your settings.php file automatically with the initial username, password, and database name. These credentials are easy to find, using either lando info from the command line or Docker’s dashboard. I set up both my D7 and D9 sites with Lando, and once I used lando info to view my D7 site’s hostname and database credentials, connecting my D9 site to the D7 site’s database went off without a hitch.

4. Use Git to version-control your work. If you are new to Git, this is a good time to start using it. I have both my old D7 and new D9 sites wired to separate Git repositories, which I use for file version-control. After initiating a git repository in your site directory, you can create a .gitignore file to ensure that Git will not track files that you do not want local and remote versions of your site to share. For me, these include settings.php and the files directory. You can deploy a Git-wired site by pushing it to a cloud service like Github, Acquia Cloud, or Bitbucket, and then pulling it to your server. Meanwhile, files not wired to Git can be pushed up using another method, such as SFTP.

5. Plan to make database backups frequently. As you prepare your D7 and D9 sites, make database backups of both sites so that you can keep snapshots of your progress. Making backups will allow you to roll back either site to an earlier database version if necessary. If you are using Lando, you can export and import using lando db-export <databasepath> and lando db-import <databasepath> while at the root of your site.

Drupal 7 Setup

6. Develop a plan for controlling change on your live site. You typically cannot repeat a second migration with the same Drupal 8 or 9 database once your initial migration has occurred, so if possible, it is best to move over all your database essentials in one go. If you expect your D7 site’s content to continue evolving, talk with your team about when the best time to migrate the site is — as well as whether configuration, content, users, and other aspects of your D7 site should be frozen at a particular time. If content updates do need to cease, discuss when and for how long.

7. Identify the status of each Drupal 7 module. Research the modules your D7 site has and categorize them. Some may be compatible with Drupal 9, some may have been moved to Drupal core, and some may not be compatible. Additionally, some modules that are compatible with Drupal 9 may still be in alpha and beta states, in which case they are likely not to have upgrade paths.

8. Create a pre-migration instance of your Drupal 7 site. While you may have a working local copy of your D7 site, it is best to create a new instance that can be more streamlined with fewer modules turned on. It will likely look different from your fully-functioning local version, and that’s usually fine — as ultimately, it is just a place from which the D9 instance will pull data and files.

9. It is best to turn off Drupal 7 modules that do not have upgrade paths. Doing so will simplify your upgrade and prevent errors, though it may also mean having to delete the associated fields, configurations, or other site assets to prevent migration errors. In these cases, you will need to take additional steps to make sure the Drupal 9 site ends up with these fields and configurations, either by manually re-adding them or by using custom code to support their migration.

10. Clear the Drupal 7 database log before importing it locally. Before making your migration instance and after backing up your D7 database, I recommend clearing the database log in admin/reports/dblog. For me, it made my database dump smaller and easier to import into my pre-migration D7 site instance — as the watchdog table, which initially had been unreasonably large, ended up being far smaller after I had cleared the logs. Just back up up your D7 database before clearing the logs in case you want to check them for some reason.

Drupal 9 Setup

11. Become familiar with Drupal 9’s environment requirements. This will help you make sure your local production environment and remote server are set up properly. For instance, you will see from the Environment requirements of Drupal 9 that D9 requires PHP 7.3 and Apache 2.4.7. With respect to local setup, Lando should configure the correct PHP version automatically, but other local setup tools may not.

12. Use a fresh Drupal 9 database with no content or configuration. Refrain from adding any content or content types, and do not configure anything. Only turn on the modules you think you will need, such the migration modules that come bundled with Drupal: Migrate, Migrate Drupal, and Migrate UI. Besides enabling the migration modules, I also turned on the Entity module.

13. Be careful about Drupal 9 modules that are not yet stable. Sometimes, turning on modules in their alpha or beta states can cause issues with your database that interfere with the migration. You can ensure that you only download stable modules by keeping your composer.json minimum version set to stable, but this may not always be practical if your site will rely heavily on modules that do not yet have stable releases. If it is important for your site to use a module that only has an alpha or beta release for Drupal 9, downloading it and keeping it disabled should not affect your database. If you need to enable it, make a database backup before doing so in case enabling it adversely affects your site’s database. Once you think you have the necessary modules enabled, go to /upgrade to begin the migration.

14. Learn to export and import database configurations.

    So let’s say two weeks go by after you run the database migration. As you are admiring your wonderful new D9 views, you find out that despite your best efforts to control change, numerous content updates have occurred on your D7 site. And you quickly begin to realize that all these D7 updates now require you to wipe out your D9 database and re-run the migration to import all that new content. Fortunately, Drupal 8 and 9 allow you to export database configurations to config files using either a Drush workflow or a Drupal UI workflow. And once you have those config files sitting comfortably in their sync directory, you can import them back into a different version of your site’s database — either one in a different environment (such as dev, stage, or production) or one in the same environment but at a different state. So before you drop all those tables and start that migration over again, try exporting your D8 or D9 configuration. Then you can start up with a fresh Drupal site, re-run the migration, and import the configurations you exported — which should contain those views you built — back into your database. That way, you can bring in your new content while resurrecting those lovely Drupal 9 views.

Troubleshooting Issues

15. Check the list of modules that will not be upgraded. After you connect to your D7 database, you will likely still see a list of D7 modules that will not be upgraded. Once you see the list, you may want to turn off additional modules and restart the migration.

16. Take notes during and after the migration. During the migration, you will see messages conveying both progress and any errors. The messages will change quickly, so if you see errors, I recommend copying and pasting representative ones into a text editor. After the migration, check the database logs on your D9 site at /admin/reports/dblog to study errors, warnings, and other messages further.

17. Develop strategies for content that may not automatically move over. For me, this included content handled by the Field Collection and Video modules, which were not upgraded. This is where you may want to either manuallly re-add the content on your D9 site or try running custom scripts or simply re-adding content to your Drupal 9 site.

18. If you have a complex site, or if you have stubborn upgrade errors produced by parts of your site that you really need, there are more complex migration approaches that offer more options and flexibility while also requiring additional coding, additional modules, and a more complex Lando configuration.

    • One method involves using two additional modules: Migrate Plus and Migrate Tools, using Drush. While figuring out the order of steps can be a learning curve, it enables more granular control of your migration.
    • One such method was presented in this Lando Migration Webinar by John Ouellet, who is well versed in Drupal migrations. I do recommend watching this webinar to get a sense of this type of approach, especially if the process here, which focuses mainly on the essentials, does not move over enough of your content or configuration.

Big Picture

19. Plan your post-data migration site build. After migrating the database, the rest of the migration is often a rebuild. Do not expect views or all your layouts to make it over, and anticipate rebuilding your theme using a Drupal 9 starter sub-theme. Plan to re-adding views and other configurations. This part of the process will largely be akin to building a new site.

20. Consider using migration as an opportunity to rethink your site. Even though building a D9 site with the same design and site architecture as your D7 version can help to make your upgrade plan straightforward, the fact that you have to rebuild your site pages and theme anyway means that there is an opportunity to rethink design, navigation, and other site aspects — so decide whether you want to use your migration as an opportunity to give your site a new look.

Thanks for reading, and I hope these tips help you with your Drupal migrations.