Drupal: Drush

by Gisle Hannemyr

The Drupal shell (drush) is a very useful tool that is used via the CLI to help with administrative taks for a Drupal website.

Table of contents

Introduction

To help with adminsitration of a Drupal site, there exists a Gnu/Linux command line shell and scripting interface for Drupal named drush – the Drupal shell.

For installation instructions, please see the section Install drush globally in the chapter about installing Drupal version 7.

Basic usage

Drush just types out a list of the most used commands if you start it without any arguments. Drush also provides an extensive help system that describes both drush commands and topics of general interest. Try the following three commands to learn more about what drush can do. The first shows a list of all drush commands. The next to shows menus that let you dig deeper into the built-in help system.

$ drush
$ drush help --filter
$ drush topic

You may also supply of a command as an argument to help. Example:

$ drush help cache-clear

The drush core comes with lots of useful commands for interacting with code like modules, themes and profiles. It can also be used to update the configuration, execute SQL queries, migrate databases, and to executes miscellanious commands, such as running cron or clearing the cache.

In this section I shall list the most useful commands to give you an idea about what drush can do.

See alsoFor a longer list of drush commands, visit Peter Brady's website Drush Commands. This is a search­able reference are the core Drush commands for Drush versions 6, 7, 8 and 9 – as well as the major contributed modules that declare their own Drush commands (Views, Features, Devel, Display Suite etc.). There is also online documentation at Drush.org.

Here is how to display what version of drush you're running.

$ drush version
 Drush Version   : 8.1.15

The above command does not interact with the site and will work everywhere. However, for most drush commands, you need to be in or below your webroot when invoking drush. Otherwise drush does not know how to locate your Drupal settings file, etc. Assuming that your webroot is /var/www/html, here is a command that gives an overview over your Drupal installation:

$ cd /var/www/html
$ drush status
Drupal version        : 7.64
…

On a multisite, drush will act on the default site, unless you use the @sites to make the following command apply to all sites. To apply the command to a single site that is part of a multisite, position yourself in the directory holding the settings.php of the site.

Many drush commands come in two versions – long and short. They're equivalent. For instance, to show a list of recent log entries (watchdog messages), you may use one of the following two commands:

$ drush watchdog-show
$ drush ws

This may be helpful when the site only is able to show a blank page (WSOD).

To delete all watchdog messages:

$ drush wd-del all

Clearing, updating and rebuilding

If you've changed something in the front-end, and the change is not visible on the site, clearing all the caches often help:

$ drush cache-clear all
$ drush cc all

Actually, not all caches are flushed. To flush all (or some) of the caches holding preset image styles, do:

$ drush image-flush
$ drush if

To run drupal-cron from the CLI, do:

$ drush cron

The following command will update Drupal core and contributed projects to the latest available release:

$ drush pm-update
$ drush up

notePlease note that since drush replaces old project directories with new, any modifications you've made to the project directory will be overwritten. Some projects (in particular those using a two-phase install for external libraries) will break if updated in this way. For more about this please see the segment about updating projects and themes in a previous chapter.

The above commands will also automatically run the database update script if necessary. To explicitly run the database update script, use this command:

$ drush updb

The following pair of commands will first update the shared code base of a multisite, and then run the database update script on all the sites in the multisite.

$ drush up
$ drush @sites updb

The Drupal 7 registry is a list of PHP classes and the files they go with. If you move or rename a component, you may break the registry so bad that Drupal is unable to boostrap. Such problems cannot be repaired with the recgular cache-clear activity because some class is required when the system is trying to bootstrap.

$ drush registry-rebuild
$ drush rr

If drush don't recognize registry-rebuild, you may need to download it first.

Download, enable and disable

To download Drupal contributed projects (i.e. modules or themes) from Drupal.org and place them in the correct directory below the webroot on your website, use the following command below the site's webroot:

$ drush dl -y list

The list is the short name of one or more projects.

Use this command to enable or disable projects:

$ drush en -y list
$ drush dis -y list

You can use the * wildcard at the end of a name.

Localization update

The Localization update project adds three commands that may be used from the CLI:

drush l10n-update         # Update translations.
drush l10n-update-refresh # Refresh information  of all available projects.
drush l10n-update-status  # Show translation status of all available projects.

To get the translation updated you need to refresh the information before checking status. The following sequence of commands shows how it works:

$ drush l10n-update-status
…
my_project (7.x-1.x)   Up to date
…
touch my_project.7.x-1.x.nb.po
$ drush l10n-update-status
…
my_project (7.x-1.x)   Up to date
…
$ drush l10n-update-refresh
Checked translation for advanced_help
…
Checked available interface translation for 31 projects.
$ drush l10n-update-status
…
my_project (7.x-1.x)   Local update available
…
$ drush l10n-update
Fetching update information for all projects /all languages.
Found 1 project to update.
Updating translations
…

Other useful drush commands

To see a list of all non-core enabled modules, and the version that is installed, use one of the following commands:

$ drush pm-list --no-core --status=enabled
$ drush pml --no-core --status=enabled
$ drush @sites pml --no-core --status=enabled -y

The first two are just the long and short version of the same command. The third will do a full inventory of all enabled modules on a multi-site.

To see a list of all the variables that is defined for a specific site, use vget Similarly, you can use vset to set a variable or to change an existing variable to a different value. To delete a variable, there is vdel. Examples:

$ drush vget > variables.txt
$ drush vset foobar 'FOOBAR'
$ drush vget foobar
foobar: 'FOOBAR'
$ drush vdel foobar

For instance, to set a site to maintenance mode and then exit it, using drush:

$ drush vset maintenance_mode 1
$ drush vset maintenance_mode 0

Here is a handy pair of commands to get and set the variable file_public_path when converting a sub-site of a Drupal multi-site to a single site.

$ drush vget file_public_path
file_public_path: sites/example.com/files
$ drush vset file_public_path sites/default/files

To reset the password for user admin:

$ drush upwd --password="password" admin

To remove some PII (currently the email address and password) from the datebase before moving a production database to an outside contractor or a staging server, there is sql-sanitize/sqlsan. The pattern for the email replacement in the sanitization operation may contain the following replacement patterns: %uid, %mail or %name. Using the argument “no” disables the santizen action. Examples:

$ drush sql-sanitize --sanitize-email=no  --sanitize-password=no
$ drush sqlsan --sanitize-email=u%uid@localhost  --sanitize-password=pw

The first command will do nothing. The second command will change all email-addresses to “u1234@localhost” (where the number is the uid) and the password for all users to “pw”.

noteThis command changes these fields directly in the database. Never run it on a production site.
It may not be fully GDPR compliant. The database may contain other fields with PII, such as user names and phone numbers.

Troubleshooting

Sometimes after a botched composer command, drush stops working. The typical symptom is that drush responds “The drush command X could not be found” for every X, including cc and version, or that you get an error like this: “sh: 0: getcwd() failed. No such file or directory.” The following two commands usually fixes this condition:

$ drush cc all # outside the webroot directory
$ drush cc all # inside the webroot directory

Other sections discussing drush

Special uses of Drush is also discussed elsewhere in the ebook. The relevant links are these:

Final word

Last update: 2018-01-30 [gh].