Read on for more about this command-line shell and scripting interface for Drupal.
During its ten-year rise to prominence, Drupal dramatically has changed the way people use it to build Web sites. Without needing to write a single line of code, Drupal users are able to build complex, custom Web sites through the point-and-click Web interface. The problem is I hate Web interfaces.
To be fair, the rise of keyboard shortcuts in modern Web applications has made them far more comfortable for me, but I don't like mice (and don't even get me started on trackpads). I am a keyboard kind of guy; hands on home row make me happy.
Even for those of you proficient with your pointing devices, there still are times when you just can't beat the elegant power of the command line. As Linux users, you have all experienced the sheer joy of a simple shell script to automate repetitive tasks (and if you haven't, why not?). There is a long list of scenarios where using Drupal's Web interface is either inefficient or inconvenient, but the truth is, for most Web developers and sysadmins, the command line is a comfortable place.
Drush (DRUpal SHell) is a command-line shell and scripting interface for Drupal, a veritable Swiss Army knife designed to make life easier for those of us who spend some of our working hours hacking away at the command prompt.
Drush began several years ago as a project to provide a command-line interface to Drupal. Although somewhat limited in its early utility, Drush has matured to become an essential tool for many Drupal developers and administrators (myself included).
The current version, 4.1, brings a ton of great new built-in commands, plenty of internal cleanup and better support for Drupal 7. Arguably more exciting, however, is the growth of add-ons and extensions for Drush. Although not a traditional Drupal module, Drush is highly extensible via its own API. A large number of existing Drupal modules now include Drush commands in their official releases.
Initial versions of Drush required a working Drupal installation prior to installing Drush. Since version 2, however, Drush has become Drupal-version-independent. You don't need a working Drupal site to install Drush. In fact, as you will see shortly, you can use Drush to install your Drupal site fully.
Installing Drush on Debian/Ubuntu systems is as simple as running apt-get install drush. However, the current stable Debian/Ubuntu versions include packages for Drush 3. To get the latest and greatest, or if you're on a system without a Drush package, you need to go through a few extra steps:
Make sure you have a working version of PHP CLI. This generally can be accomplished by installing the php5-cli package on your system.
Download Drush from drupal.org/project/drush (I am currently using the “All-versions-4.1” release). Extract the downloaded package (.zip or .tar.gz) and place it where you won't lose it. I typically place Drush in ~/local/drush on my development machines and /usr/local/drush on servers, but the location is flexible.
Get the drush command into your $PATH. You can make this happen in several ways. Drush includes a shell script (called drush) that tries to determine the “best” PHP interpreter to use and runs the drush.php PHP script. I typically symlink this script into a directory already in my $PATH (ln -s /usr/local/drush/drush /usr/local/bin/drush). Alternatively, you can add the path of your Drush install to your $PATH or provide your own shell alias to the PHP script itself. See the included README.txt file for full details.
To test your new Drush install, you should be able to run drush status in your terminal and see output something like this:
PHP configuration : /etc/php5/cli/php.ini Drush version : 4.1 Drush configuration : Drush alias files :
If that worked, it's time to let the real fun begin!
Although Drush works without an existing Drupal installation, it is certainly much more fun with one around. In fact, one of the most fun uses of Drush is to install new Drupal sites. Normally, this process would include something like: browse to drupal.org, click Get Started, then click Download Drupal, then click to download the tar.gz file. Extract that package into your Web server's document root. Create a database for your new Drupal site. Browse to your new Drupal install (that is, http://localhost/drupal) where you will be tossed into the installer. Begin clicking your way through the installer (where you'll likely be asked to chmod your settings file), and after seven or more screens, you'll have a working Drupal install. Of course, chances are good that from here you'll go on to download a handful of modules (again, browsing drupal.org and extracting zip files) and clicking through the interface to turn them on and configure them.
Phew, that's a lot of clicking!
Okay, it's not so bad when you are installing your first Drupal site, but it takes a lot of time with your mouse, and if you install (or re-install) Drupal sites a lot, it can become tedious. Let's look at that process with Drush:
Change into your Web server's root directory (cd /var/www).
Run drush dl drupal-7.0. This downloads Drupal 7.0 from drupal.org and extracts the files into /var/www/drupal-7.0.
Change into the newly created directory (cd /var/www/drupal-7.0) and run the site-install command:
drush site-install --db-url=mysql://root:secret@localhost/drupal
Answer “y” to the following prompt, and in a few short moments, you'll have a working Drupal install (using the “drupal” database on localhost). To verify, you can browse to http://localhost/drupal-7.0/ and log in using admin/admin as the user name/password, respectively. The site-install command has several additional options; run drush help site-install for full details.
What if you need a handful of Drupal-contributed modules for your site (as most people do)? Don't reach for your mouse yet! Let's grab “views” and “devel” while we're here (still in our Drupal directory):
drush dl ctools views devel drush en views views_ui devel
(Note that ctools is a required dependency for Views in Drupal 7.)
The Drush dl command (a shortcut for pm-download) is very clever about how it downloads the modules and where it places the extracted folders. By default, it grabs the .tar.gz file from drupal.org and places folders inside the sites/all/modules directory, but you have full control (including using CVS checkouts or where the folders belong). See drush help dl for full details.
As with most tools, people develop their own habits with Drush, but here are a few built-in commands you are likely to appreciate (at least in time):
drush cc (or cache-clear): Drupal developers learn early on to “clear the cache” while developing, because Drupal aggressively caches its more complex internal data structures. Chances are good that if you're writing code, you have a terminal window nearby, and running drush cc all will ensure that when you check your latest work in the browser, you'll accurately see the most recent changes.
drush cron: the Drupal installation guide (INSTALL.txt) recommends running Drupal's periodic maintenance tasks by adding a crontab entry that uses wget to fetch http://example.com/cron.php periodically. In Drupal 7, this now requires a generated “cron_key” parameter as part of the URL to inhibit nefarious requests. Using Drush eliminates the need for the key and avoids tying up a Web server process to do periodic maintenance.
drush up (or pm-update): this command checks drupal.org for new releases for all installed modules and offers to download all updates and run the database upgrades for you. It even handles that pesky, easily forgotten “backup first” step.
Running drush help in your Drupal directory always will give you the list of currently available commands (based on modules installed and so forth). For more information on each command, run drush help <command>.
You may have noticed that we ran our drush commands above from inside the Drupal install directory. This allows Drush to determine which Drupal site (and configuration options) to use. However, for those looking for a bit more freedom and particularly those working within Drupal “multi-site” environments, you need to make use of the --root and --uri switches for Drush. This can lead to a lot of repetitive typing. If you have only a single Drupal site, you can specify these options (and lots more) by creating a .drushrc.php file in your home directory. See the example.drushrc.php file in the examples folder of your Drush installation for more details.
For those of you who work on several Drupal sites across various versions and installations, Drush provides an “alias” mechanism to define the common parameters. To create an alias for this example site here, you can create a file ~/.drush/aliases.drushrc.php containing the following PHP code:
$aliases['example'] = array( 'root' => '/var/www/example/drupal', 'uri' => 'example.com', );
Now you can run drush commands for your example site from any directory using drush @example <command> (for example, drush @example status). To make things even better, aliases can reference remote sites (accessible via SSH) by including the remote-host and remote-user options. See the example.aliases.drushrc.php file from the examples folder in your Drush install directory for full details.
With each new release, Drush includes more commands, and Drupal modules are increasingly offering Drush commands with their releases. If that's not enough (and you aren't afraid of writing some PHP), you can write your own Drush commands. The examples folder in your Drush install includes a sample command, make-me-a-sandwich (XKCD fans rejoice!), for those interested in learning more.
One of the greatest testaments to the power of Drush is the Aegir Hosting Platform (see Resources), which provides a mass-hosting environment (with support for multiserver installations). Although it includes a Web interface, Aegir does all of its heavy lifting via custom Drush commands.
If you work with Drupal and hate using your mouse (or prefer your terminal), Drush can save you countless hours of clicking and open a whole new world of scripted Drupal tasks.