Using Drush Aliases

October 10, 2011

“Drush is Awesome!”

You have probably read that on every single blog that has ever mentioned Drush. That is because it is!

I’ve been using Drush for the past year and a half and it has simplified my Drupal life immensely. In the back of my mind, I knew it could do more. I had been putting off learning Drush aliases for some stupid reason. I’m kicking myself for it!

Aliases are commonly used to define short names for local or remote Drupal installations; however, an alias is really nothing more than a collection of options.

Aliases are amazing because they unlock some of the coolest and most powerful features of Drush. The two commands we want to take advantage of are sql-sync and rsync. Sql-sync let’s you move your database from one Drupal install to another, like moving the live database down to the staging or development server. Rsync let’s you do an incremental sync of directories in the same manner. No more creating a tarball of your files directory and using wget to move it around.

Drush comes with a handy example.aliases.drushrc.php file to explain things and get you started. We’ll take a look at that in a second, but let’s look at what we need to get aliases working:

  • We need to be working on a *nix box. Sorry windows, it just doesn’t work quite right.
  • We need to have Drush installed on the servers we want to use. In this example we’ll be working with a local dev box and a staging server.
  • We need to have our SSH keys setup WITHOUT a passphrase.

Getting your alias file(s) setup

The example aliases file can be found in drush/examples/example.aliases.drushrc.php. We can put this file in a couple places but for this example we’ll just place it in the root of our Drush install. We can name the file: aliases.drushrc.php but it’s common practice to name the alias files with a ‘group’ name that refers to the site they are going to be referencing. I’m going to call my file: matttarsi.aliases.drushrc.php. Jump into the file and read through the options or skip to the bottom and start copying the examples. For our local machine, we setup our alias like so:

$aliases['dev'] = array(
    'root' => '/home/quickstart/websites/matttarsi.dev/',
    'db-url' => 'mysql://user:password@localhost/dbname',
    'path-aliases' => array(
      '%files' => 'sites/default/files',
  • $aliases[‘dev’]: Change the ‘dev’ to whatever you’d like your alias called. Since we are using a group name, this alias will be @matttarsi.dev.

  • ‘root’: This is the root of your Drupal install. This can’t be a relative path. Use ‘pwd’ to determine the path from the command line.

  • ‘db-url’: This is the connection string to your Drupal database. It should look very similar to the D6 settings file.

  • ‘path-aliases’: An array of common paths for rsync. This lets you define where the files directory is for example (shown above). Options can be seen in the example file, you can also define custom directories.

Once you have your dev alias setup, run ‘drush sa’ to verify that Drush has found your new alias. You can also run ‘drush @group.alias status’ (drush @matttarsi.dev status) to view the status of the installation. You can now run this command outside of your Drupal installation!

terminal screenshot

Setting up your staging server is similar but it contains a few extra options to tell it where to connect to.

$aliases['stage'] = array(
    'uri' => 'stage.matttarsi.com',
    'root' => '/var/www/matt/data/www/stage.matttarsi.com/',
    'db-url' => 'mysql://user:password@localhost/dbname',
    'remote-host' => 'stage.matttarsi.com',
    'remote-user' => 'ssh-user',
    'path-aliases' => array(
      '%files' => 'sites/default/files',
     'command-specific' => array (
       'sql-sync' => array (
         'no-cache' => TRUE,
  • ‘uri’: This should always be the same as the site’s folder name in the ‘sites’ folder.
  • ‘remote-host’: This is the remote domain or IP address of the server you’ll be connecting to.
  • ‘remote-user’: This is the user to connect as. You’ll need to make sure that user has your public key in the authorized_keys file.
  • command-specific: An array that allows you to specify options for this alias. In this example, we want to exclude the cache tables when the @matttarsi.stage alias is used.

Now we have two aliases and can start to have fun ;) Run the same drush sa command to see your new alias.

terminal screenshot

Now run @matttarsi.stage status. If everything worked properly, you should see the status report from your staging server!

This opens the door for us to sync our files directory from our staging server to our dev server incrementally:

drush rsync @matttarsi.stage:%files @matttarsi.dev:%files

Drush is even more awesome because when you run this it will prompt you with a message asking:

You will destroy data from /home/quickstart/websites/matttarsi.dev/sites/default/files and
replace with data from ssh-user@stage.matttarsi.com:/var/www/matt/data/www/
Do you really want to continue? (y/n):

You want to sync your database? No problem!

drush sql-sync @matttarsi.stage @matttarsi.dev

With the sql-sync command you can also use the ‘–sanitize’ option to obscure the email addresses in the user table and prevent accidentally emailing all the users in your database when you are testing those forms!

Note: It’s also recommended when using the sql-sync command that you setup ‘%dump’ or ‘%dump-dir’ in the path aliases section of your alias. This will get you faster file transfers via rsync.

Combine this with your favorite version control system and you’re starting to get a nice workflow!