An Absolute Beginner's Guide: Getting Started with Drush

Drupal Shell (or Drush) is probably the most critical / useful tool for use on Drupal projects other than Drupal itself. While it may not sound super fancy (since it replicates, more or less, a bunch of stuff that you can do through the UI anyway) believe me, it’s life changing. Why?

  • you can run commands faster on the terminal (even if you’re really bad at using terminals)

  • you can run commands in many different environments (local / dev / stag / prod / etc) without having to log in many places

  • it’s more secure than username / password authentication (since it utilizes ssh keys)

  • you can automate commands during ci / deployments

This article is all about getting started with Drush in 2020. If you are new to Drupal (or have been living under a rock) this is something you should definitely prioritize!

Installing Drush

Right up front I want to acknowledge that there are a few ways to install Drush. Why? Because we are still dealing with a number of different versions of Drupal in the ecosystem and necessarily that means there are some different versions of Drush as well.

The preferred way of installing for Drupal 8 and 9 is via composer. This means that Drush becomes a dependency of your project and it can be run via vendor/bin/drush on your project.

composer require drush/drush

If you happen to be running Drupal 7 still, obviously this isn’t going to work because Drupal 7 doesn’t use composer. In that circumstance you can still install a Global drush.

Global vs. Local Drush

Global Drush means that you are installing Drush on your host machine / webserver and it’s the same everywhere. This is the older method of installing Drush.

Installing Drush via composer is more contextual to that project. Why is this better? The TLDR is that it treats Drush like any other dependency on the project and acknowledges that different projects may need different versions of the same dependency simultaneously. Drush is software and like any software there are new features / bug fixes / bugs being introduced on a regular basis.

Setting up Drush Aliases

Once Drush is installed, the next step is to setup aliases. An alias allows you to communicate with one or more environments with your drush commands. Let’s look at Drupal GovCon as a quick example.

When we’re working locally, we don’t actually need an alias in this case. Why? Because we are using Lando on the project and when we run a command like lando drush status we are running inside the container and the default alias is just “self.” So it runs on itself.

lando drush status
 Drupal version   : 8.9.6                             
 Site URI         : http://default                    
 DB driver        : mysql                             
 DB hostname      : database                          
 DB port          : 3306                              
 DB username      : drupal8                           
 DB name          : drupal8                           
 Database         : Connected                         
 Drupal bootstrap : Successful                        
 Default theme    : twentynineteen                    
 Admin theme      : claro                             
 PHP binary       : /usr/local/bin/php                
 PHP config       :                                   
 PHP OS           : Linux                             
 Drush script     : /app/vendor/drush/drush/drush     
 Drush version    : 10.3.1                            
 Drush temp       : /tmp                              
 Drush configs    : /app/vendor/drush/drush/drush.yml 
                    /app/drush/drush.yml              
 Install profile  : lightning                         
 Drupal root      : /app/docroot                      
 Site path        : sites/default                     
 Files, Public    : sites/default/files               
 Files, Private   : /app/files-private                
 Files, Temp      : /tmp    

On the other hand, if we want to run a command on one of our cloud environments, we have to run a slightly different command:

lando drush @dgc.dev status
 Drupal version   : 8.9.6                                                 
 Site URI         : http://capitalcampdev.prod.acquia-sites.com           
 DB driver        : mysql                                                 
 DB hostname      : staging-7801                                          
 DB port          : 3306                                                  
 DB username      : s8093                                                 
 DB name          : capitalcampdev                                        
 Database         : Connected                                             
 Drupal bootstrap : Successful                                            
 Default theme    : twentynineteen                                        
 Admin theme      : claro                                                 
 PHP binary       : /usr/local/php7.3/bin/php                             
 PHP config       : /usr/local/php7.3/etc/cli/php.ini                     
 PHP OS           : Linux                                                 
 Drush script     : /mnt/www/html/capitalcampdev/vendor/drush/drush/drush 
 Drush version    : 10.3.1                                                
 Drush temp       : /mnt/tmp/capitalcampdev                               
 Drush configs    : /etc/drush/drush.yml                                  
                    /mnt/www/html/capitalcampdev/vendor/drush/drush/drush 
                    .yml                                                  
                    /mnt/www/html/capitalcampdev/drush/drush.yml          
 Install profile  : lightning                                             
 Drupal root      : /mnt/www/html/capitalcampdev/docroot                  
 Site path        : sites/default                                         
 Files, Public    : sites/default/files                                   
 Files, Private   : /mnt/files/capitalcamp.dev/sites/default/files-privat 
                    e                                                     
 Files, Temp      : /mnt/tmp/capitalcampdev  

If you read carefully, the output between those two commands is almost identical. However, the first one is from the Lando container for local development and the second one is from out Acquia cloud development environment. All because I passed that @dgc.dev alias into the command.

Important Note: the only reason that I was able to run the command was because I have ssh keys configured for my Acquia cloud account. We have open sourced this code (and you could download it yourself right now). If you provision the Lando vm you can totally run the first command! However, if you try to run the second one it will fail with a permission denied unless you are explicitly granted access to our Acquia hosting account.

The alias is a simple enough matter to define. If you look at the the drush/sites/dgc.site.yml site you’ll see several aliases defined. Here’s the dev one:

dev:
  host: staging-7801.prod.hosting.acquia.com
  options:
    ac-env: dev
    ac-realm: prod
    ac-site: capitalcamp
  paths:
    drush-script: drush
  root: /var/www/html/capitalcamp.dev/docroot
  uri: capitalcampdev.prod.acquia-sites.com
  user: capitalcamp.dev

Note that the name of the file is arbitrary, but defines the first part of the alias. So @dgc comes from the name of the file. The second part of the alias (the .dev) comes from the dev key in the file. You can name these aliases whatever you want! But I do advise having aliases for all of your common environments on a given project and I recommend committing those files into your project repo so that your team can utilize them in the same way.

Using Drush

I use Drush on every project every day. So it’s hard for me to tell you “how” to use Drush, because I use it for just about everything all the time. Here’s the list of Commands (there’s a lot). Having said that, once you have it configured there are a few common tasks that I would suggest your prioritize:

Logging Into Sites

From a security perspective, one of the first things I do on any site is totally randomize the credentials for user/1. Then we entirely rely on Drush to log into that site. When adding aliases into the mix, one can rapidly log into any site in any environment with a single command.

drush user:login
drush uli

Protip: you can also pass a --name parameter into the Drush command so you can log in as a particular user.


Clearing the Cache

One of the most common needs during development (and deployments) is to flush / clear the cache. Obviously this is one that should be done sparingly in production, but it’s super useful in the right cicumstances.

drush cache:rebuild
drush cr

Note: in previous versions of Drupal / Drush this was:

drush clear-cache
drush cc


Installing the Site

This command does a clean installation of Drupal. This one is great for resetting your local environment to a clean state before you start building a feature!

drush site:install
drush si

Synchronizing the DB

Similar to the install command, these commands are great for replicating a cloud environment in your local environment for testing / development purposes. Warning it is critical that you get the pattern correct or you’ll accidentally overwrite your cloud db with your local one!


Importing Configuration

As I’ve discussed as part of configuration workflow it’s quite important to be able to import configuration. This command will do just that!

drush config:import
drush cim


Exporting Configuration

Similarly, you also need to export configuration changes as you do local development.

drush config:export
drush cex



A note on Commands

Most of these commands have additional options and parameters that you append to further customize them.

Many of these commands can have significant, destructive impact on your environment / codebase. Make sure you read what you’re doing and understand the implications!

Custom Drush Commands

As with most things in Drupal 8/9, if what you want doesn’t exist you can write it yourself! I haven’t done a post on this topic yet, but watch for it in the coming weeks.

In Conclusion

Drush isn’t a core component of Drupal and it’s maintained by a group of volunteers in the community. A special thanks to Moshe Weitzman and the nearly 300 contributors that make Drush possible and keep it working. Drupal development would be a drastically different experience without this tool.

Related Content