CODEX

20 Tips for Drupal Database Migrations

Nevin Katz
Mar 13 · 9 min read
Photo by Chris Briggs on Unsplash

Background

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.

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 technology, and indeed, Docker downloads with Lando 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, either by typing lando info from the command line or by inspecting 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 are inordinately large or should not be shared across environments. 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

  1. Develop a plan for controlling change on your live D7 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.
  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 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 local migration website instance, I recommend going to <sitename>/admin/reports/dblogand clearing the database log. 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

  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. On local sites, 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, 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.
  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 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 <sitename>/upgrade to begin the migration.
  4. 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

  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 <sitename>/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 manually re-add the content on your D9 site or try running custom scripts.
  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 also requiring additional coding, additional modules, and a more complex Lando configuration.
  • Another method is presented in this Lando Migration Webinar recording by John Ouellet, who is well versed in Drupal migrations. I do recommend watching this webinar to get a sense of this type of method, especially if your site is too complex for the web browser approach.

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 your D7 views or layouts to make it over, and anticipate re-adding views and other configurations, as well as rebuilding your theme using a D9 starter sub-theme. 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.

CodeX

Everything connected with Tech & Code

Nevin Katz

Written by

Developer • Tech & Science Writer • Editor of All Things Science. Subscribe to my email list at https://buttondown.email/nevkatz for article roundups!

CodeX

CodeX

Everything connected with Tech & Code

Nevin Katz

Written by

Developer • Tech & Science Writer • Editor of All Things Science. Subscribe to my email list at https://buttondown.email/nevkatz for article roundups!

CodeX

CodeX

Everything connected with Tech & Code

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store