Drush Aliases: What, Why, and How

They are called drush aliases, and they are your friends. You know, like how your Swiss army knife is your best pal, or how your bash profile takes you out for drinks on Friday night. Well, maybe it just allows you to drink that Friday evening beer a little sooner than you otherwise would have, because you aren’t sitting there typing the world’s longest terminal command only to find out that after you hit return, you left out a very important argument and are now going to have to spend the next 3 hours reconstructing all of the files you just accidentally excommunicated to digital limbo.

What is a drush alias?

A drush alias is quite simply a shortcut to a remote Drupal site. It is in essence a tunnel through which drush commands can be issued. The alias is configured via a php array which gets saved into a php file. Once configured properly, executing any drush command on any remote server you have shell access to is as simple as this:

[~] drush @remote [command]

Need to clear the cache after a theming update?

[~] drush @production cc all

Need to check the status of a feature after messing around in the admin interface?

[~] drush @dev fl

And my personal favorite, syncing a remote database with your local environment:

[~] drush sql-sync @staging @self

Why use drush aliases?

Because less typing equals beer sooner. Drush aliases will save you time just like Drush itself saves you time. If you have ever been frustrated and exasperated because for the hundredth time you have to pull the database from staging to your local machine which involves the tedious process of logging in via ssh, navigating to the proper directory, running a SQL dump, mis-typing the destination path, moving the misplaced file, forgetting the destination path in the process, logging out, using scp to download the dump file, mistyping that path, realizing you don’t have permission to download that file, logging back in… you get the idea. A drush alias is the answer to this common nightmare.

How to use drush aliases

Which brings me to the part of the story for which you are waiting with baited breath. “How can I be part of this wondrous beer-expediting thing you refer to as drush aliases?” So here it is, the anatomy of a drush alias file:

<?php  // prod.alias.drushrc.php  $aliases['prod'] = array(  // needs to match server name as configured in vhost  'uri' => 'astonishdesign.com',          // Drupal's root directory for that site (not the sites/* folder)   'root' => '/var/www/astonishdesign.com/htdocs',           // FQDN or IP of server hosting site (think ssh [email protected])   'remote-host' => 'astonishdesign.com',           // A user on the remote host for which you have an ssh key set up   'remote-user' => 'sam',  );

A few key things to note here:

Filename must be of the form alias-name.alias.drushrc.php
Array key ($aliases[‘this part’]) must match alias-name as it reads in the filename
This configuration assumes you have set up public/private key authentication for ssh
alias-name becomes the string used in the drush commands, e.g. @alias-name.
Where does this file live? (psssst, you have to keep reading!)

Useful side note, the ‘root’ parameter can be a symlink. So if you regularly create builds of your Drupal site named after the release branch in source control, create a symlink to the most current build and your alias file will always reference the latest build. Nifty!

So where does this file live on my local machine? That is an excellent question. There is a simple easy answer, and there is a much cooler, slightly more complicated answer.

Easy Answer: Stick alias files in ~/.drush This is the default location that drush will search when looking for alias files. However, this means all of your alias files will be saved in one place and not with the project they belong to. Which leads us into the slightly more complicated answer.

Slightly more complicated answer: As you can probably tell by the way the file is named, this alias refers to a production server. This would seem to indicate that a useful way of setting this up is to have multiple aliases per site, say dev, staging and prod. But what if you are working on multiple sites? How does drush find the dev, staging, and prod alias files for each site you are looking for? The answer lies in knowing how to configure drush.

~/.drush/drushrc.php

is drush’s config file. If you use git for version control, you have access to a function that will return the path to the root of your git repository. This is an excellent place for a .drush folder to live, because now, your alias files can live with the project they pertain to, and under version control. The drushrc.php file looks like this:

<?php  // ~/.drush/drushrc.php  exec('git rev-parse --show-toplevel 2> /dev/null', $repo);  if (!empty($repo)) {  $repo = array_shift($repo);  $options['config'] = $repo . '/.drush/drushrc.php';  $options['include'] = $repo . '/.drush/commands';  $options['alias-path'] = $repo . '/.drush';  }

This tells drush to include any alias files it can find in git repositories that have a .drush folder.

IMPORTANT!

drush sql-sync @self @prod

Oh #%! I just blew away the production database! *#&[email protected]! &*@! This is why we recommend using a drush policy file. Not only will there be less cursing, but probably more beer-drinking opportunities as well. The policy file stops you from pushing a local database to a remote site via a drush alias. It looks a little something like this:

<?php  // ~/.drush/policy.drush.inc  /**  * Implementation of drush_hook_COMMAND_validate().   */  function drush_policy_sql_sync_validate($source = NULL, $destination = NULL) {   if($destination == '@prod' || $destination == '@staging') {   return drush_set_error(dt('Per ./.drush/policy.drush.inc, you almost overwrote the production database you moron!'))   }  }

I find that when my computer insults me, I learn more quickly.

Additional Resources

If you are interested in the configuration options that are available for drush aliases, check out

Troubleshooting:

```
[~] drush sa
```
This will list alias files that drush can find from this working directory. If your alias is missing, make sure the filename is correct, make sure the array key matches the filename, and make sure the alias file is in the correct location.
If the alias file still doesn’t show up, check drushrc.php and make sure the function for include alias files is implemented correctly.
Do you have SSH set up properly?
```
[~] drush sa @alias-name
```
should spit out the contents of the alias file. If it does not, there is a PHP syntax error in your alias file.

So in conclusion, drush aliases are the Drupal Deity’s gift to the universe. Happy Drupal-ing!