Drush aliases

I'm trying to get a better handle on Drush aliases, so figured it would help to write out my findings and thoughts. This post may update as we go, so look back for changes.

Drush context

Drush runs in specific contexts, if Drush can tell that it's in a Drupal root somewhere, it will assume the --root=/path/to/that/Drupal. It can also detect if you're within a sites/subsite directory and will set --uri=subsite as well. This is very handy as I am often doing other command line tasks in the terminal window, so if I'm already in a specific location, Drush will assume that location as the context. cd ~/Sites/drupal/sites/subsite.vmdev drush status is equivalent to: drush --root=~/Sites/drupal --uri=subsite.vmdev status Not much savings, but when you have to clear caches, run cron, check watchdog entries multiple times, it's nice not to have to add those all the time.

Drush Aliases

The other way of setting context is with Drush aliases. In the examples directory, there is an example.aliases.drushrc.php file. Copy this file either to the .drush directory in your home directory or to the same directory where the drush script lives. There are a couple of other places that Drush will automatically search for alias files and they're documented in example.aliases.drushrc.php. To begin with, rename the copied file to aliases.drushrc.php. There are other naming patterns that you can use, but we'll get to those later. A basic drush alias is an associative array that defines all the necessary properties of the site that you're going to try to alias. Let's make an example alias to our subsite.vmdev site which is on my local machine and in the main Drupal multisite. To define an alias, you create a keyed item in the $aliases array. The key should be what you would like to call the alias. In our case, subsite. Once we have the definition, we need to add the Drupal root and the URI to the definition: '/Users/erikp/Sites/drupal', 'uri' => 'subsite.vmdev', ); ?> This allows drush to know which specific drupal site we're referring to no matter what directory we happen to be in. So now we can run commands against the new alias by using the @aliasname syntax with drush: drush @subsite status

Remote aliases

One powerful feature of drush is its ability to communicate with Drupal sites on other servers over SSH. Aliases can take advantage of this as well by using the remote-host and remote-user keys in the site alias definition: 'myserver.eporama.com', 'root' => '/home/www/drupal-6.22', 'uri' => 'mysite.eporama.com', ); ?> This would create an alias to the website that has a URL of mysite.eporama.com which lives on the server myserver.eporama.com and has a different path to where Drupal is installed. Now, from my local machine, not logged into the remote machine, I can still use drush: drush @real_site status

MySQL Dumps

If you're going to be running drush sql-dump or drush sql-sync, it helps to let drush know where you'd like to have the dump files stored. You can do this by specifying a dump-dir. However, dump-dir is actually a sub variable of path-aliases. 'myserver.eporama.com', 'root' => '/home/www/drupal-6.22', 'uri' => 'mysite.eporama.com', 'path-aliases' => array( '%dump-dir' => '/home/erikp/drush-dumps', ), ); ?> When sql-sync runs, it first dumps the database on the source server, then copies the dump file to the target server, and finally imports the dump file into the target database server. The dump-dir is where it will store these dump files. If you call for a second sql-sync within 24 hours, drush will assume that the existing dump file is good enough. If you need to get a fresh sql file, you can add the parameter --no-cache. To sync two databases, you specify the source database first and then the target database: drush sql-sync @real_site @subsite

Parental Aliases

Once you have a significant number of aliases defined (probably more than two), you'll start to notice that there is a lot of repetition. Every site on the same multisite needs the same root the same dump-dir, etc. Luckily, you can take these common pieces and group them together in a single alias and then use that alias inside of other aliases. '/Users/erikp/Sites/drupal-6.22', 'path-aliases' => array( '%dump-dir' => '/Users/erikp/drush-dumps', ), ); $aliases['subsite'] = array( 'parent' => '@local-site', // this refers to the alias defined above 'uri' => 'subsite.vmdev', ); ?> The subsite alias inherits the information from the local-site alias. In my aliases file, I have defined three "parent" aliases on which all of my other aliases are based. They are local, dev, and prod which give the remote-host, root, dump-dir for my local machine and our development and production servers. Then for each new site, I can quickly create three new aliases one for each environment: '@local', 'uri' => 'new-site.org', ); $aliases['dev.new-site'] = array( 'parent' => '@dev', 'uri' => 'new-site.org', ); $aliases['prod.new-site'] = array( 'parent' => '@prod', 'uri' => 'new-site.org', ); ?>

Multiple Alias files

You can also keep multiple alias files if that would help keep things more organized for you. I have a file for work Drupal sites (edc.aliases.drushrc.php) and a separate file for non-work sites that I work on (my.aliases.drushrc.php). This way, I can share the work site alias file with the other developers in our office and it helps keep things organized and makes sure that when I recommend running drush @oursite cc all that the alias will be the same for each of us. Drush will look for these files in a number of places, but the most common is to put them in a folder called aliases in your $HOME/.drush directory. If you would like to have them in a specific location, you can specify any path you want in drushrc.php.