Upgrading CiviCRM is a critical task for maintaining the security, stability, and performance of your organization's database. While the standard web-based upgrade process is functional, it can be time-consuming and prone to timeouts on larger sites. If you are running CiviCRM on Drupal, you have access to a much more powerful tool: Drush. To upgrade CiviCRM with Drush is to take control of your environment, allowing for faster execution, better logging, and scriptable workflows.

In this guide, you will learn the different methods for upgrading CiviCRM via the command line, how to monitor progress during long-running database updates, and the best practices to ensure your data remains safe throughout the process.

Why Use Drush for CiviCRM Upgrades?

The traditional CiviCRM upgrade path involves manually replacing files and then visiting a specific URL (civicrm/upgrade?reset=1) to trigger database migrations. While this works for small installations, it has several drawbacks:

  • Timeouts: Large database migrations can exceed PHP's max_execution_time when run through a browser.
  • Lack of Feedback: The web UI progress bar can sometimes hang or fail to show detailed error messages.
  • Manual Steps: Handling tarballs and file permissions manually increases the risk of human error.

Drush (Drupal Shell) eliminates these hurdles by interacting directly with the server's CLI, providing a robust environment for heavy lifting.

Pre-Upgrade Checklist

Before you touch your production environment, you must perform the following preparation steps. Skipping these is the most common cause of upgrade failure.

  1. Test on Development: Never perform an upgrade on a live site first. Clone your site to a staging environment and run the full process there.
  2. Full Backups: Take a snapshot of both your Drupal/CiviCRM codebase and your CiviCRM database. You can use Drush for the database dump: bash drush civicrm-sql-dump > ~/civicrm_backup_$(date +%F).sql
  3. Clear Caches: Start with a clean slate to avoid conflicts with cached container definitions. bash drush cc all
  4. Maintenance Mode: Prevent users from modifying data during the upgrade. bash drush vset maintenance_mode 1

Method 1: Using the Automated cvup Command

CiviCRM includes a specific Drush command called civicrm-upgrade (alias cvup). This command is designed to handle both the codebase replacement and the database migration in one go.

To use this method, you need the path to the new CiviCRM tarball and a directory where Drush can store a backup of the existing code.

bin/magento setup:install \
--db-host=localhost \
--db-name=magento_db \
--db-user=dbuser \
--db-password=dbpass \
--base-url=https://yourdomain.com/ \
--backend-frontname=admin_path \
--language=en_US \
--currency=USD \
--timezone=America/Chicago \
--use-rewrites=1

Potential Issues with cvup

In some older versions or specific server configurations, you might encounter an error stating: 'Your database has already been upgraded to version X.X.X'. If this happens even though you are moving to a newer version, simply re-running the command often resolves the state mismatch. However, because cvup attempts to manage files for you, many developers prefer the more granular control of Method 2.

This is the preferred method for most experienced CiviCRM administrators. It involves manually replacing the module folder and then using Drush specifically for the database migration logic. This ensures that file permissions and directory structures remain exactly as you intend.

Step 1: Replace the Codebase

Navigate to your modules directory (usually sites/all/modules) and remove the old CiviCRM directory before extracting the new one.

bin/magento module:enable --all

Step 2: Run the Database Upgrade

Once the new code is in place, use Drush to execute the database migrations. This is the CLI equivalent of visiting the upgrade URL.

bin/magento setup:upgrade

Alternatively, if you have the cv utility installed (a dedicated CiviCRM CLI tool), you can use:

docker kill $(docker ps -q)
docker rm $(docker ps -a -q)
docker volume prune

Monitoring Long-Running Upgrades

If you are jumping across several major versions (e.g., 5.30 to 5.60), the database upgrade can take a significant amount of time. Since Drush doesn't always show a progress bar for every internal SQL task, you can monitor the progress in a second terminal session.

Log into the CiviCRM SQL console:

wzxhzdk:4

Then, query the version stored in the domain table to see which migration step the system has currently reached:

wzxhzdk:5

As the upgrade runs in your first terminal, repeating this query in the second will show the version number incrementing as each migration script finishes.

Post-Upgrade Cleanup and Localization

After the database upgrade reports success, there are a few final housekeeping tasks to ensure the UI behaves correctly.

1. Clear Template Caches

CiviCRM compiles Smarty templates, and these can become stale after an upgrade. Delete the contents of the templates_c directory:

wzxhzdk:6

2. Update Localization Files

If your site uses a language other than English, you must update your .mo files. Download the latest localization tarball and extract it to: sites/all/modules/civicrm/l10n

3. Flush All Caches and Bring Site Online

Finally, clear the Drupal caches and disable maintenance mode.

wzxhzdk:7

Frequently Asked Questions

Can I upgrade CiviCRM across multiple major versions at once with Drush?

Yes, CiviCRM is designed to run all intermediate migration scripts. If you are upgrading from 5.10 to 5.50, the cvupdb command will sequentially execute every update script between those versions. However, the risk of failure increases with the size of the jump, so verify your backups carefully.

What should I do if Drush returns a 'Permission Denied' error?

This usually happens if Drush is run as a different user than the one who owns the web files (e.g., running as root instead of www-data). Always try to run your Drush commands as the web user to maintain correct file ownership: sudo -u www-data drush cvupdb.

Is the cv tool better than Drush for upgrades?

The cv tool is a modern, standalone CLI for CiviCRM. While Drush is excellent for Drupal-integrated sites, cv is often faster and works across WordPress and Joomla too. Using cv upgrade:db is functionally identical to drush cvupdb and is highly recommended for modern workflows.

Key Takeaways

  • Automation is safer: Using Drush avoids the timeout issues common with web-based upgrades.
  • Manual codebase replacement is often cleaner: Deleting the civicrm folder and extracting a fresh tarball prevents "file leftovers" from older versions.
  • Monitor via SQL: Use select version from civicrm_domain; to track progress during long updates.
  • Don't forget the cleanup: Always clear templates_c and update localization files after the database migration is complete.

By incorporating Drush into your CiviCRM maintenance routine, you turn a complex, manual process into a streamlined, professional workflow.