Background

Picture it. You are happily working away on your Drupal 7 site when you see a webinar announcement, an email, or a calendar note reminding you of the inevitable: Drupal 7 is losing support in November 2022.

Whether you are new to Drupal or a seasoned Drupal veteran, the migration process, which consists of 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 some time soon and would like some guidance on making a plan, here are a few tips I gleaned on the database part from my own migration experiences. In this case, the focus is on migrating a Drupal 7 site’s database to Drupal 9 through the web browser, though I do allude to more complex 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 there are other approaches that 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 you end up migrating from D7 to D8 and are using some modules that D8 supports but D9 will not. 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, Bitbucket, and then pulling it to your server, and then by pushing up your files 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

  1. Develop a plan for controlling change on your live site. You typically cannot repeat a second migration once your initial migration has occurred, so to ensure that all the essentials move over in one go, 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. Once migration begins, it is ideal if nothing further is changed on the live Drupal 7 site, but if updates to your live D7 site do have to happen during your migration, discuss how they would be added to the Drupal 9 site.

  2. 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.

  3. 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.

  4. 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 in order 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.

  5. 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 site instance, as the watchdog table held far less data that way.

Drupal 9 Setup

  1. 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.

  2. 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. Besides enabling the migration modules, I also turned on the Entity module.

  3. 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. 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 relies heavily on modules in their alpha and beta states. If it is important for your site to use a module that only has an alpha or beta releases for Drupal 9, downloading it and keeping disabled should not affect your database. If you need to enable it and test it, make a database backup before doing so since enabling them could adversely affect your site’s database before the migration.

  4. Enable the Drupal 9 migration modules. On Drupal 9’s Extend panel, turn on all the Migration modules: Migrate, Migrate Drupal, and Migrate UI. Once they are on, go to <sitename>/upgrade to get started.

Troubleshooting Issues

  1. 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.

  2. 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.

  3. 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.

  4. If necessary, consider more complex approaches. 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 requiring additional coding, additional modules, and a more complex Lando configuration.

    • One method involves using two additonal modules: Migrate Plus and Migrate Tools, using Drush. (With Lando, running a drush command should be prefixed by lando drush rather than just drush.) While figuring out the order of steps can be a learning curve, it enables more granular control of your migration.
    • Another 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

  1. 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.

  2. 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.