Last updated 1 November 2017. Created on 11 January 2012.
Edited by leeomara, kentr, drupalmonkey, Chroid. Log in to edit this page.

For the latest example see the Drush GitHub repo (version 8.x).

The following example is a template to create aliases for a local site and the site on a development server.

<?php
/**
 * @file yoursite.aliases.drushrc.php
 * Site aliases for [your site domain]
 * Place this file at ~/.drush/  (~/ means your home path)
 *
 * Usage:
 *   To copy the development database to your local site:
 *   $ drush sql-sync @yoursite.dev @yoursite.local
 *   To copy your local database to the development site:
 *   $ drush sql-sync @yoursite.local @yoursite.dev -structure-tables-key=common --no-ordered-dump --sanitize=0 --no-cache
 *   To copy the production database to your local site:
 *   $ drush sql-sync @yoursite.prod @yoursite.local
 *   To copy all files in development site to your local site:
 *   $ drush rsync @yoursite.dev:%files @yoursite.local:%files
 *   Clear the cache in production:
 *   $ drush @yoursite.prod clear-cache all
 *
 * You can copy the site alias configuration of an existing site into a file
 * with the following commands:
 *   $ cd /path/to/settings.php/of/the/site/
 *   $ drush site-alias @self --full --with-optional >> ~/.drush/mysite.aliases.drushrc.php
 * Then edit that file to wrap the code in <?php ?> tags.
 */

/**
 * Local alias
 * Set the root and site_path values to point to your local site
 */
$aliases['local'] = array(
  'root' => '/path/to/drupal/root',
  'uri'  => 'yoursite.localhost',
  'path-aliases' => array(
    '%dump-dir' => '/tmp',
  ),
);

/**
 * Development alias
 * Set up each entry to suit your site configuration
 */
$aliases['dev'] = array (
  'uri' => 'yoursite.dev',
  'root' => '/path/to/drupal/root',
  'remote-user' => 'ssh-username',
  'remote-host' => 'ssh-host',
  'ssh-options'  => '-p 2222',  // To change the default port on remote server
  'path-aliases' => array(
    '%dump-dir' => '/tmp',
  ),
  'source-command-specific' => array (
    'sql-sync' => array (
      'no-cache' => TRUE,
      'structure-tables-key' => 'common',
    ),
  ),
  // No need to modify the following settings
  'command-specific' => array (
    'sql-sync' => array (
      'sanitize' => TRUE,
      'no-ordered-dump' => TRUE,
      'structure-tables' => array(
       // You can add more tables which contain data to be ignored by the database dump
        'common' => array('cache', 'cache_filter', 'cache_menu', 'cache_page', 'history', 'sessions', 'watchdog'),
      ),
    ),
  ),
);

/**
 * Production alias
 * Set each option to match your configuration
 */
$aliases['prod'] = array (
  // This is the full site alias name from which we inherit its config.
  'parent' => '@yoursite.dev',  
  'uri' => 'yoursite.com',
  'root' => '/path/to/drupal/root',
  'remote-user' => 'ssh-user',
  'remote-host' => 'ssh-host',
);
?>

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

toleillo’s picture

You can use this command on the command line of the server to show the correct configuration and add this to the alias.drushrc file.

drush site-alias @self --full --with-optional

You get something like this, you can paste to your aliases file and change with your own alias like "local", "dev" or "prod".

$aliases['self'] = array (
  'root' => '/var/www/XXX',
  'uri' => 'http://default',
  'path-aliases' => 
  array (
    '%drush' => '/usr/bin',
    '%site' => 'sites/default/',
  ),
);

juampynr’s picture

Added to the comment at the heading. Thanks!

drupaal’s picture

Hi,
How to pull files outside drupal path (example: /root/folder1 and /root/folder2) from a remote server to a local server.

Thank you.

glazzies’s picture

You can use rsync to sync files down, either through drush or manually.

To rsync files down with drush:

drush rsync @sitename.prod:/path/to/files /path/to/local/destination

mark.labrecque’s picture

If your server does not allow password authentication, try being explicit with your ssh key in your alias file:

$aliases['drupal.dev'] = array(
  'uri' => 'drupal.dev',
  'root' => '/var/www/drupal',
  'remote-host' => 'drupal.dev',
  'remote-user' => 'ssh_user',
  'ssh-options' => '-o PasswordAuthentication=no -i /path/to/ssh_key',
);
simon.westyn’s picture

The command mentioned:
drush site-alias @self --full --with-optional >> ~/.drush/mysite.aliases.drushrc.php
This won't work because the php tags are missing <?php ?> in the mysite.aliases.drushrc.php file.

tomhung’s picture

This should work. You will still need to edit it and change 'self' to another alias.
echo '<?php' > ~/.drush/mysite.aliases.drushrc.php && drush --root=/var/www/docroot site-alias @self --full --with-optional >> ~/.drush/mysite.aliases.drushrc.php

christopher.mcandrew’s picture

Thanks for that. Sometimes it easy to forget the obvious. I couldn't figure out why it wasn't working. Much appreciated.

twfahey’s picture

Got here from Google, appreciated the quick knowledge drop, helped me out with a CircleCI Integration script I am writing. Awesome! Thank you!

japicoder’s picture

Due to the upgrade of my site from Drupal 8.3.7 to 8.4, I had to upgrade to drush 9. Found that Drush 9 doesn't use yoursite.aliases.drushrc.php anymore and you have to define your alias using a YAML configuration file.
To help the migration, you can run drush site:alias-convert which will convert your old aliases.drushrc.php into aliases.alias.yml.

Here is an example file: https://raw.githubusercontent.com/drush-ops/drush/master/examples/example.aliases.yml

ccshannon’s picture

"you can run drush site:alias-convert which will convert your old aliases.drushrc.php into aliases.alias.yml."

Doesn't work for me:

Existing aliases (for ALL my instances locally, so I don't have to manage them separately) located at "/Users/USERNAME/.drush/aliases.drushrc.php"

My CWD is '/Users/USERNAME/.drush/'.

$ drush site:alias-convert

 Absolute path to a directory for writing new alias files [/Users/USERNAME/.drush/sites]:
 > 

legacy_files: {  }
converted_files: {  }


It creates an empty '/Users/USERNAME/.drush/sites' folder, migrates nothing.

re: the example file ... where does one put a "single site" version of this file? In a project's drush folder? In the docroot/web 'sites' folder?

I'm not entirely clear on how to implement per-site alias files by hand, was hoping the alias-convert command would do it for me.

Thanks for any insight anyone can give. I feel I must be doing something wrong, here, or missing something obvious.

japicoder’s picture

@ccshannon, it's been some time since I tested it, but I can give you some tips about how it should work.

I have a D8 site installed on /var/www/d8-project. Into this folder I have a drush folder with an aliases.drushrc.php, then the full path is /var/www/d8-project/drush/aliases.drushrc.php

My aliases.drushrc.php contains:

<?php
# NOTE: this file will be deprecated in Drush 9 in favor of site-aliases/d8-project.alias.yml

$aliases['local'] = array (
  'root' => '/var/www/d8-project/web/',
  'uri' => 'http://d8-project.localhost',
);

$aliases['staging'] = array (
  'root' => '/var/www/d8-project/web/',
  'uri' => 'https://d8-project-staging.com/',
);

$aliases['testing'] = array (
  'root' => '/var/www/d8-project/web/',
  'uri' => 'https://d8-project-testing.com/',
);

After upgrading to Drush 9 and running the drush site:alias-convert command, I found that it created a new folder site-aliases into the drush folder, with a d8-project.alias.yml file containing:

local:
  root: /var/www/d8-project/web/
  uri: 'http://d8-project.localhost'
staging:
  root: /var/www/d8-project/web/
  uri: 'https://d8-project-staging.com/'
testing:
  root: /var/www/d8-project/web/
  uri: 'https://d8-project-testing.com/'

As you can see, what the command simply does, is to take all your defined aliases and generate a new YAML file with them.
Can't give you more details, but apparently your problem seems to be that the aliases.drushrc.php is not parsed properly or directly not found.

ccshannon’s picture

Thanks so much for that, @japicoder! This is very helpful for being able to construct an alias without the converter! :)

Just FYI for anyone having my issue, I figured out why my attempts yielded no results ... I typically store ALL my site aliases in one file (~/.drush/aliases.drushrc.php) on my local so I can control these from one place ... but the site:alias-convert command is not looking for a file with that name ... it is looking for *.aliases.drushrc.php, meaning there has to be a root name.

Here's what I did ... I copied my aliases.drushrc.php file to "bob.aliases.drushrc.php" (just random 'GROUPNAME') as detailed in the drush alias file documentation.

Then I ran:

drush site:alias-convert --sources=~/.drush

and it spit out one new alias file per site as listed in the 'bob' file -- e.g. "mysite.site.yml"! :)

Note, it also spit out a bob.site.yml (there is no bob site; it's just a made up groupname) which is empty and throws an exception when running "drush sa" against it. I just deleted that yml file.

My issue here now is ... even though this is great for when I am using my site's project folder as CWD (because I have placed the new *.site.yml file in my project/drush/sites folder) I work on enough projects at once that I like using the aliases for when I am NOT cd'd into a particular project, but want to run drush commands for it. Again, this is not for higher environments like dev/staging/production, where it makes sense to have each project have its own set of alias files. This is just my local system where I do a lot of experimenting and build/destroy lots of drupal instances.

The drush alias documentation talks of drush reading the central drush.yml file for aliases (on my system that is located at ~/.composer/vendor/drush/drush/drush.yml) before looking in the local drush/sites/ location. I'm not sure how to update it properly, but really that's not a blocker, just more a personal preference.

I'm all good now! Thanks!!!