Upgrading CiviCRM for Drupal 8/9/10¶

About this document

Use this document to upgrade CiviCRM installations on Drupal 8/9/10 to the latest CiviCRM release.

The document assumes that:

CiviCRM and Drupal 8/9/10 are already installed and working.
You are able to run composer and manage composer.json.
You have identified the root of your Drupal project -- such as /var/www/example.org.

Before upgrading

Make sure you have done the steps listed in before upgrading first.

Drupal 8/9/10 (D10) sites are typically administered with Composer. Composer is a dependency management tool which can add, upgrade, and remove software packages for your site.

CiviCRM is published as a suite of related packages. Our goal is to use Composer to update CiviCRM's code. Then, we can upgrade the database.

Review "composer.json"¶

The file composer.json lists a series of required packages. Each package has a version constraint. For example, a typical file might specify:

{
  "require": {
    "civicrm/civicrm-core": "~5.29.0",
    "civicrm/civicrm-packages": "~5.29.0",
    "civicrm/civicrm-drupal-8": "~5.29.0",
    "civicrm/civicrm-asset-plugin": "~1.0.0"
  }
}

Look at your configuration and answer these questions:

What is the version constraint?

In the above example, it uses a version-constraint: ~5.29.0. This matches 5.29.0 and roughly-equivalent versions (5.29.1, 5.29.2, etc). However, it does not match 5.30.0.

A common alternative might be ~5.29. This matches 5.29 and roughly-equivalent versions (5.30, 5.31, etc). However, it doe not match 6.0.

If the constraint looks unfamiliar, review Composer: Writing Version Constraints.

Which plugin is responsible for CiviCRM's JS+CSS files?

CiviCRM-Drupal (8/9/10) requires a composer plugin to handle JS+CSS assets. There are two common plugins. composer.json may specify:

civicrm/civicrm-asset-plugin: Used on newer deployments. Better compatibility with different variations of Drupal 8/9/10.
roundearth/civicrm-composer-plugin: Used on older deployments. Better compatibility with older versions of CiviCRM.
Neither: The significance of omission depends on the version. For CiviCRM v5.31+ (Nov 2020), omission implies civicrm/civicrm-asset-plugin. In older versions, omission is likely a misconfiguration.

For our purposes, we assume that you should keep the current plugin. Switching to a different plugin requires extra effort.

What if both plugins are listed in composer.json?

This is most likely a mistake. The signifance depends on the versions:

If civicrm/civicrm-asset-plugin is 1.1.1 (Oct 2020) or newer, it will defer to roundearth/civicrm-composer-plugin.
If civicrm/civicrm-asset-plugin is older, then the behavior is unknown/undefined/unsupported.

Upgrade the plugin¶

If composer.json lists civicrm/civicrm-asset-plugin as ~1.0.0, then it needs the first update.

composer require civicrm/civicrm-asset-plugin:~1.1

Otherwise, continue to the next step.

Upgrade the code¶

Choose one of the following methods:

Run the command composer update. This finds the newest version which matches the current constraint. For example, if the constraint specifies ~5.29.0, then composer update will find 5.29.2 or 5.29.3 or similar.
```
composer update civicrm/civicrm-{core,packages,drupal-8} --with-dependencies
```
Run the command composer require. This changes the current constraint. For example, to switch to ~5.31.0, run:
```
composer require civicrm/civicrm-{core,packages,drupal-8}:~5.31.0
```

Upgrade the translations¶

In some workflows for internationalized deployments, you would need re-download the translations.

Upgrade the database¶

Choose one of the following methods:

Run the following cv command from within your site:
```
cv upgrade:db
```
Tip: Preview upgrade steps

The cv upgrade:db command accepts a --dry-run option to show what changes will be executed. For the maximum detail, use cv upgrade:db --dry-run -vv.
Or, run the following drush (v8) command from within your site:
```
drush civicrm-upgrade-db
```
Or, point your web browser to the following URL and follow the on-screen instructions.
```
http://example.org/civicrm/upgrade?reset=1
```

Additional cleanup¶

The upgrade must reset various resources (such as file-caches, database-caches, and public-assets). Several of these steps are automatic, but automation isn't perfect. You may find it advantageous to manually reset some resources after an upgrade.

At various times, these additional cleanup steps have been useful:

Delete cache files with rm

rm -rf sites/default/files/civicrm/templates_c/`

Clear database caches with drush or cv
```
drush cache-clear civicrm
```
```
cv flush
```
Re-publish static assets (*.js, *.css, etc) with composer
```
composer civicrm:publish
```

The above steps should not normally be necessary, but they may help with customized workflows or with unresolved bugs. If you identify a scenario where these steps are necessary, please report an issue. (For example, dev/core#4754 reports about a scenario with asset publication.)

Finally, you should recall if you did any special modifications during the upgrade. If so, you may need to undo them. For example:

If you enabled maintenance mode, then you should switch back to production mode.
If you disabled any conflicted modules, then you may want to re-enable them.