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.
Drush is a critical tool for Drupal development. Here’s a getting started guide!