An introduction to Drush: The Drupal power tool

What is Drush?

Drush is a tool that allows you to perform common Drupal tasks from the command line. According to the Drush project page:

Drush is a command line shell and scipting rinterface 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.

To give a quick example, I can use Drush to enable a module by opening a command line and typing:

# cd /path/to/drupal/
# drush en views

Why use Drush?

So, why would you use Drush when Drupal already provides such nice user interfaces (especially with D7)? There are two main reasons I use Drush: speed, and scripting.

Speed

Using a command line tool to do common tasks is generally faster than using the web-based interface. This is very well demonstrated by the Development Seed video: Drush: More Beer, Less Effort. If you don’t have time to go watch that however, I’ll provide a quick comparison.

Here is a list of things you need to do to install and enable the views module manually with Drupal:

• Open a web browser
• Go to the project page: http://drupal.org/project/views
• Download the tarball
• Find the tarball in your file system and unzip it
• Move the unzipped contents to the appropriate folder in your Drupal installation
• Go back to the web browser and find the modules admin page
• Find the module in the list, check its box to enable it, and hit Save

Compare the above list with the steps to complete the task with Drush:

• Open a command line
• Type cd /path/to/my/drupal/install
• Type drush dl views -y
• Type drush en views -y

That’s it. No searching through your Downloads folder to find the zipped module; no scrolling through an enormous list of modules trying to find the one you just installed. Just three short commands.

Scripting

The other advantage of command line tools like Drush is that you can run the commands from within a script. This is particularly handy if you find yourself doing a few things repeatedly. We will look at this in a little more depth later on, but suffice to say that a few well-written scripts can save you a lot of time and hassle.

Installing Drush

Even though Drush is listed as a module on the drupal.org website, it’s not really a module. To install it, you need to download the tarball from the project page and unzip it somewhere sensible. On my Mac, I have it installed under ~/Library/drush.

Note: If you want to use Drush in a Windows environment, do not install it anywhere with a space in the file path. For example, installing Drush under C:\Program Files\drush is a bad idea. Try C:\drush instead.

Once you have the package saved somewhere you will also need to add this location to your $PATH environment variable. This will save you having to type something like ~/Library/drush/drush every time you want to run a drush command.¹

Once you’ve done this, you should be able to fire up your command line and do the following:

# cd /path/to/drupal
# drush status

If your server is running, you should see a summary of some key information about your Drupal install.

There is a lot more to be said about installing Drush, and I thoroughly recommend reading the helpful README.txt file that comes included with the package. Of course, you already do that with everything you download from drupal.org, and this all goes without saying.

Useful Commands with Drush

So, just what can you do with Drush? Here is a list of commands that I find handy:

Command	Description
drush dl <module name>	Download and install a drupal module (defaults to the sites/all/modules directory)
drush en <module name>	Enable a module
drush dis <module name>	Disable a module
drush up	Check for available updates, download updated modules and run update.php
drush up <module name>	Check to see if the specific module needs updating, and if so, download it and run update.php
drush sql-dump --result-file=db-backup.sql	Dump the entire Drupal database into a file called db-backup.sql. In other words, backup your database.
drush sql-cli < db-backup.sql	Connect to the database server and run the commands in db-backup.sql. In other words, restore the database from db-backup.sql
drush cc all	Clear all caches
drush vset preprocess_css 0 --yes	Turn off CSS caching (useful when developing themes)
drush vset preprocess_js 0 --yes	Turn off JavaScript caching
drush cron	Run cron
drush vset site_offline 1 --yes	Put a site into maintenance mode (D6 only)
drush vset maintenance_mode 1 --yes	Put a site into maintenance mode (D7 only)
drush vset site_offline 0 --yes	Take a site out of maintenance mode (D6 only)
drush vset maintenance_mode 0 --yes	Take a site out of maintenance mode (D7 only)

Drush Site Aliases

One of the very cool things about Drush is that, if you have SSH keys installed, then you can run commands remotely. That is, if I have Drush installed on both my local machine, and another remote machine, I can tell Drush to SSH into my remote server and run a command there. For example²:

drush username@server.com/path/to/drupal#mysite.com status

Now, you may be thinking that seems like a lot to type out—-you might as well just SSH into the server yourself and run Dush there—-and you would be right. This is where Site Aliases come in.

What is a site alias?

Site aliases are shortcuts to specify that you want to run a Drush command on a specific Drupal site. For example, it would allow you to type the following instead of the long command above:

drush @mysite status

Drush would then look up the details for mysite, SSH into the remote host, run the status command and display the results.

How to set up site aliases

Site aliases do take a little bit of work to set up, but they are definitely worth the effort. To get started you’ll need to create a directory called .drush inside your home directory. To find out what your home directory is, type the following:

# cd ~
# pwd

Inside the .drush directory you’ll need to create a file called aliases.drushrc.php.

Let’s assume for the sake of the example that you have a Drupal site running on your local machine at localhost, and another running on a server at example.com.

To set an alias for the local site, save the following into your aliases.drushrc.php file:

<?php

$aliases['local'] = array(
  'uri'  => 'localhost',
  'root' => '/path/to/my/drupal/install, // This must be a full full path, not a relative one
);

Once this is done, you should be able to type drush @local status, and get a status listing. Now, that may not seem all that exciting, but once you have this alias installed, you can run that command from whatever happens to be your current directory. So, I can, for example, type:

# cd ~/my_random_directory
# drush @local status
  Drupal version                :  7.0                                        
  Site URI                      :  localhost                             
 [...]

# cd some/other/random/directory
# drush @local status
  Drupal version [...]

Now, that’s not bad, but as mentioned above, the real magic is being able to do this from your local machine, without having to log in. To set this up, we need set up a few things first:

1. First, you will need Drush installed on your remote machine and added to the $\_PATH (as described above).
2. You will also need to created an SSH key pair so that Drush can log in to the remote server securely, without having to ask you for a password.³

3. You then need to add a slightly longer alias entry to your ailases.drushrc.php file:

   <?php
   
   $aliases['remote'] = array(
     'uri'          => 'example.com',
     'root'         => '/path/to/my/drupal/install',  // This is the path on the remote server
     'remote-host'  => 'example.com',
     'remote-user'  => 'myusername',
     'path-aliases' => array(
       '%files' => 'sites/default/files',
     )
   );
   

Once all this is done, you should be able to type drush @remote status and get the status of your remote server. You can also run commands like drush @remote up, or drush @remote en views. This can come in very handy when, for example, you need to quickly clear the cache on a remote server.

Using Drush in a script

One of the really useful things about Drush is that because you can run it from the command line, you can also run it from a script. For example, if you have a number of site aliases set up and you’d like to backup the database on each of them, you could write a script something like the following:

backup-drupal-sites.php:
  <?php

  $aliases = array( '@alpha', '@beta', '@gamma', '@epsilon' );

  foreach ($aliases as $alias) {
    shell_exec("drush $alias sql-dump --result-file=my-backup-file.sql");
  }

Then, from the terminal, you could simply type php backup-drupal-sites.php to backup the database across all four sites.

If you’d like more on the kinds of things you can do with Drush in a script, check out Drupal Release Management with Drush and Git

The limitations of Drush

While Drush is very useful, there are still some things that you can’t do with Drush. At the moment, for example, (as far as I know) you can’t create new nodes with Drush. It would be very nice to one day type commands like:

# drush content-create-node 'Page' < MyNewPage.markdown
  New node created with id 321
# drush content-publish-node 321

And have it create a new page for me. However, it would be an incredibly complicated feature to create, so I don’t see it happening any time soon (although this Node Export feature request looks very interesting.

Probably the biggest current limitation of Drush though, is Windows support.

Drush and Windows

Drush has very limited Windows support at the time of writing, and the Drush development team are looking for people to help them sort it out. If you’d like to jump in and help, the place to start reading is: http://drupal.org/node/766080

For the moment though, I can tell you that a lot of useful commands do work in Windows. These include:

drush dl
drush status
drush core-cron
drush vset
drush cc
drush vget
drush sql-cli

A couple of very useful commands that don’t work properly yet are:

• drush updb: This one is the most inconvenient for me. So much so that I hacked together a very dodgy patch to get the updb command working (though YMMV). If you’re interested, check out http://drupal.org/node/766080#comment-4185454
• drush up: This command mostly works, but unfortunately it depends on updb to run database updates. So, it will download the new files for you, but it won’t run database updates.
• drush sql-dump: This also mostly works, but in my testing I found that it doesn’t deal with the --structure-tables-key option very well. So, if you’re happy to use it without that option, then it works well enough.

And finally, anything that requires SSH access is going to fail, so most of the usefulness of site aliases goes away. I have found a way around this, but will save that for another post.

To sum up, you can use Drush on Windows, but be careful.

Update: As mentioned in the comments below, it looks as if Drush 5.x will solve many of the problems with drush on Windows.

References

Finally, here are a few places to look if you’d like to get more information on how to use Drush:

• The Drush Project page on drupal.org
• The Official Drush Website with a full list of all the drush commands.
• Drush 3.0: More Powerful, Flexible, and Magical by Adrian Rossouw of Development Seed. A nice introduction to what Site Aliases are for.
• Drush aliases primer for Live->Dev syncing by Simon Hobbs of Em Space. A really helpful tutorial on setting up Site Aliases.