Configuration splits and upgrade maintenance

We use ‌best practices for deployment commands established by the community. You can see these as part of the drush:deploy command:

drush updatedb --no-cache-clear
drush cache:rebuild
drush config:import
drush cache:rebuild

This means that when it’s time to upgrade a module, and that module contains configuration-changing upgrades, we must do something like this on our locals:

composer update drupal/module
git add .
drush updb -y
drush cex -y
git add path/to/config
git commit -m "chore: upgrading drupal/module"

Failure to perform the step above creates a scenario where when we run our standard deploy, the configuration changes that were made in drush updb are then overridden by the older configuration stored in the configuration export folder. However, the module has marked that it has run the updates and will never run them again. If the module hasn’t done the due diligence in checking for exceptional data, this change could bring down the site, or worse, stay dormant for years, until there is a change in the code that causes the effects of the missing configuration to become noticeable.

At that point, the upgrade has been long forgotten. Figuring out that it was a configuration synchronization problem, and finding the correct upgrade hook to run to upgrade the faulty configuration, may be difficult or impossible.

There are some complications with this method if you have multiple developers touching the same configuration that is also being upgraded. Pull-request reviewers or developers in charge of upgrading the module must be diligent and catch that the changes being introduced must also be upgraded as well. Ideally, all the changes from the other features would be merged in and the upgrades would be rerun against these new features. Likewise, if the upgrades were merged before the new feature, then the new feature would be required to rerun the upgrades against their work. This becomes tricky, and sometimes, it is best to have a developer rebuild their feature after a module upgrade and export it again.

When we add a level of complication to configuration exporting, it makes the scenario of importing old configuration more likely. It’s easy to overlook all those configuration splits made for the different environments. Most of the time, the configuration and modules in these are development modules like Stage File Proxy, Devel, and Twig Xdebug.

But what happens when they are not? Let’s say, for instance, you add a field, a custom block type, or a view to a configuration split. All of these would have been affected by multiple upgrades in managing Drupal Core alone. That means that each split that contains these overrides would also need to be upgraded.

If you have one split like this, you have to double your work, making your workflow look more like this:

composer update drupal/module
git add .
drush updb -y
drush cex -y
git add path/to/config
git commit -m "chore: upgrading drupal/module for default split"

# Make your local environment pretend it's another by what ever means
# activates/deactivates different splits.

drush sql-drop
gunzip production-database.sql.gz | drush sqlc
drush updb -y
drush cex -y
git add path/to/config
git commit -m "chore: upgrading drupal/module for secondary split"

# Rinse and Repeat for each split.

In doing this, you need to be wary of how your splits are configured, because it could be that a recent upgrade applied changes that require you to update your partial splits. It’s not out of the ordinary for new properties or even completely new configuration entities with new schemas to be created/added.

Using configuration splits to provision multisite architectures is a great and interesting use case for the configuration split module. It has provided our team with insight into what we should be doing when we consider any module upgrades. I hope that our experience can prevent you from going down the same hard road of identifying missed configuration exports.