Using Drush

This page is out of date and needs reviewing.

Who is this guide for?

This guide is for developers, maintainers and designers looking to use Drush and in particular Drush aliases.

Drush Aliases

Drush 9+ (used on Drupal 8+ projects only) allows for the storage and use of drush aliases within the repository which allows us to configure and store aliases and distribute them easily to other team members, just by checking out the project repository.

An alias is some configuration that Drush can use to issue commands, often on remote servers. This becomes very useful if you want to sync the production database with your local one for example.

An alias is named and will look something like @remote.prod when used by Drush.

Prerequisites

One-time configuration

This step only needs to be done just once per computer. You may well have already done this if you've followed other documentation. If not you will need to issue the following command: ~/.lando/config.yml:

mkdir ~/.lando; echo "containerGlobalEnv:" > ~/.lando/config.yml; echo -n "  USER: " >> ~/.lando/config.yml; echo $USER >> ~/.lando/config.yml

Important! If your local user name is different from the user you ssh into servers with then you'll need to manually edit the ~/.lando/config.yml/ file to add the correct user.

Using drush aliases

If you get an error like [error] The command could not be executed successfully (returned: Permission denied (publickey). then refer to [this troubleshooting](environment/troubleshooting/#unable-to-run-remote-drush-commands-like-sql-sync.md section.

There are two drush aliases provided with each Drupal 8 site. With these two site aliases in place you can do various things. Some examples are:

  1. Clone production database to your local Lando dev site:
lando drush sql-sync @remote.prod @self
  1. Whilst on the server, clone the production database to the stage site:
cd /var/www/stage.projectname.com/gitroot/web
drush sql-sync @server.prod @self
  1. Whilst on your local development machine and within a Lando project, clone the production database to the stage site on the remote server:
lando drush @remote.prod sql-sync @server.prod @server.stage
  1. Whilst on your local development machine and within a Lando project, clone the production files to the stage site:
lando drush @remote.prod ssh "sudo drush rsync @server.prod:sites/default/files/ @server.stage:sites/default/files/"

Examples 3 & 4 are quite advanced use of drush aliases and may require some explanation:

3: We are asking lando to issue a drush command within the appserver container (lando drush) and this command is to remotely execute (@remote.prod) the drush sql-sync command, syncing the production (@server.prod) database to the stage (@server.stage) site.

4: Even more complex as we are issuing a remote command using ssh. First we ask lando to execute the drush command on the appserver (lando drush) but we pass it the remote alias (@remote.prod) and the drush ssh command so it actually executes the quoted string over ssh on the remote server. This ssh command executes drush rsync as the root user (root is needed as www-data user owns the files) and syncs the production site's public files directory (@server.prod:sites/default/files/) to the stage site (@server.stage:sites/default/files/).

Troubleshooting

When trying to run a command on the remote host, like sql-sync, you might see an error like:

Error: no database record could be found for source @remote.prod

Even though there is definitely an alias record in your local set up. This is most likely a mismatch of drush versions and possibly because the alias hasn't yet been pushed up to production.

Last updated: