Updating CiviCRM in a Composer-based Drupal environment is a significant shift from the manual 'delete-and-replace' methods of the past. While Composer offers powerful dependency management, it also introduces specific workflows that you must follow to ensure your database and codebase remain in sync. If you are using a setup based on the RoundEarth project or the modern CiviCRM-Drupal-Project scaffold, this guide will walk you through the most reliable methods to keep your installation current.

In this tutorial, you will learn how to configure your composer.json for seamless updates, how to use the CiviCRM Command Line tool (cv) to handle database migrations, and how to troubleshoot common pitfalls that developers encounter during the upgrade process.

Understanding the Composer Workflow for CiviCRM

Before running any commands, it is essential to understand that a CiviCRM update consists of two distinct phases: updating the code via Composer and updating the database schema via CiviCRM's internal upgrade scripts. Using Composer alone only handles the first part.

When you manage CiviCRM with Composer, you are typically tracking two primary packages: civicrm/civicrm-core and its Drupal-specific integration, such as civicrm/civicrm-drupal-8 (which is also used for Drupal 9 and 10). These packages must stay in version parity to avoid unexpected errors.

Step 1: Preparation and Backups

Never attempt an update on a production site without a verified backup. Because CiviCRM updates involve structural changes to the database, a failed update can lead to data corruption.

  1. Database Backup: Export your CiviCRM database and your Drupal database. Use mysqldump or a tool like drush sql-dump.
  2. File Backup: While less critical in a Composer setup, backing up your composer.json and composer.lock files ensures you can revert the code state immediately.
  3. Maintenance Mode: Put your Drupal site into maintenance mode to prevent users from triggering actions while the database is being modified.

Managing Version Constraints in composer.json

One of the most common reasons updates fail is restrictive versioning in your composer.json file. If your file explicitly requires a specific version (e.g., "civicrm/civicrm-core": "5.19.3"), running a general update command will do nothing.

To allow for easier updates, you should use semantic versioning constraints. Open your composer.json and ensure your requirements look similar to this:

{
    "require": {
        "civicrm/civicrm-core": "^5.60",
        "civicrm/civicrm-drupal-8": "^5.60"
    }
}

By using the caret (^) symbol, you tell Composer that it is safe to update to any minor version within the major release (e.g., from 5.60 to 5.61). If you want to always stay on the absolute latest stable version, you can even use "^5".

Note on the RoundEarth Plugin: If you are using the older RoundEarth setup, you may also have roundearth/civicrm-composer-plugin in your requirements. Modern installations have largely transitioned to the civicrm/civicrm-asset-plugin, but the update logic remains the same.

The Update Process: Step-by-Step

Once your version constraints are set, you can proceed with the update. The community-recommended approach involves using Composer to pull the code and cv to handle the database.

1. Update the Codebase

Run the following command to update only the CiviCRM-related packages. This prevents you from accidentally updating other unrelated Drupal modules if you aren't ready for them:

composer update civicrm/civicrm-core civicrm/civicrm-drupal-8 --with-dependencies

2. Publish Assets

In some configurations, you may need to trigger the asset plugin to ensure that CSS, JS, and image files are correctly moved to the web-accessible directory:

composer civicrm

3. Run the Database Upgrade

This is the most critical step. You can perform this through the CiviCRM web interface, but using the cv tool is much faster and more reliable for developers. If you don't have cv installed, you can add it to your project:

composer require civicrm/cv
./vendor/bin/cv upgrade:db

Using cv upgrade:db will run all pending database migrations. It provides clear output on whether each step of the migration succeeded or failed.

Troubleshooting and Alternative Approaches

Not every update goes smoothly. If you encounter dependency conflicts or "white screens of death," consider these alternative strategies used by experienced CiviCRM developers.

The "Clean Slate" Strategy

If Composer becomes hopelessly tangled with dependency conflicts, some developers prefer to start with a fresh scaffold. This involves: 1. Backing up the web/sites/default folder (including civicrm.settings.php). 2. Creating a brand new project directory using the official CiviCRM-Drupal-Project template. 3. Moving your custom files and settings back into the new structure. 4. Running composer install and then the database upgrade.

This is often faster than debugging a broken composer.lock file for hours.

Version Mismatches

If you see errors related to missing classes or database tables, verify that civicrm/civicrm-core and civicrm/civicrm-drupal-8 are on the exact same version. You can check this by running:

composer show civicrm/*

If they are out of sync, manually edit composer.json to match them and run composer update again.

Best Practices for Maintenance

  • Stay Informed: Subscribe to CiviCRM release announcements. Security releases should be applied immediately.
  • Use a Staging Site: Always run the composer update and cv upgrade:db sequence on a staging environment first. This allows you to catch extension incompatibilities before they affect your users.
  • Avoid dev-master: Never use dev-master for your version constraints in production. It is unstable and can pull in breaking changes during a routine update.
  • Check System Status: After every update, navigate to Support > System Status within CiviCRM to ensure no new requirements or configuration issues have appeared.

Frequently Asked Questions

Can I update CiviCRM using Drush?

While drush civicrm-upgrade-db was common in Drupal 7, it is less reliable in Composer-based Drupal 8/9/10 builds. The cv tool is the modern standard and is purpose-built for CiviCRM management across different CMS platforms.

What if I get a memory limit error during composer update?

Composer requires significant RAM. If your server is limited, try running the update locally on your machine, then commit the updated composer.lock file to your repository and run composer install on the server.

While the RoundEarth project pioneered Composer support for CiviCRM, the official recommendation has shifted towards using the CiviCRM Drupal Project scaffold. If you are on an old RoundEarth install, consider migrating to the standard scaffold for better long-term support.

Wrapping Up

Updating CiviCRM with Composer doesn't have to be a struggle. By maintaining clean version constraints in your composer.json and utilizing the cv tool for database migrations, you can create a predictable and scriptable upgrade path. Remember to always keep your core and Drupal-integration packages in sync, and never skip your backups. With these tools in your belt, you can keep your CRM secure and feature-rich with minimal downtime.