Using Drush and Terminus on Pantheon

Recently I’ve been using Pantheon more for client projects and have gained much more experience with using Terminus, so I decided to write this post as a place to keep track of my notes.

Terminus is a utility that allows developers to manage their Pantheon sites from their command line. Paired with Drush, it becomes an invaluable tool in your belt for creating, developing, and maintaining a Drupal site on Pantheon. I appreciate it more and more as I continue to learn of its capabilities.

Setup Drush 9

I’m not going to go into great detail about how to setup Drush on your system, but here are the basics for using Drush 9 with Drupal 8.

1. If you don’t already have it installed, install the drush global launcher. This allows you to run the drush command from anywhere within your terminal. The reason behind this utility is that as of version 9 Drush expects to be a composer dependency of each Drupal website that uses it.
2. Visit the drush installation documentation and follow along. It will tell you to require Drush be a dependency of your Drupal project, along with some optional steps. Note, we have already installed the global drush launcher.

   composer require drush/drush

3. Test that Drush is working by running the following command in your Drupal web root.

   drush status

   You should see some information about your Drupal site that Drush could only know if it is sucessfully connected to the database. For example, it should say “Database: Connected” and “Drupal Bootstrap: Successful”

Setup Terminus

Next, if you are using Pantheon and have not yet installed the Terminus command line utility, I highly recommend doing so. Use the following steps to get terminus setup:

1. Download and install the terminus utility.
2. Generate a “Machine Token” for your account on the Pantheon website. This will allow you to authenticate your computer with Pantheon.
3. Run the terminus authentication command in a terminal window, providing your new machine token.

The documentation linked to above discribes all of this is much more detail. I’m not going to duplicate the exact steps in this post.

Using Drush with Terminus

Now that you have Drush 9 working and Terminus installed, let’s test and explore the terminus command a little.

The first thing you probably want to do is get a list of your Pantheon sites: terminus site:list
Each site has a machine safe name that you will use to identify which site your commands is intended to affect. Additionally, each site on Pantheon has multiple environments. By default, the three environments are identified as dev, test, and live. If you setup additional “multi-dev” environments in your Pantheon project, each of those multi-devs are also environments that can be targeted with terminus.

Since terminus is a utility for managing all of your Pantheon sites, each drush command you send will always need to specifiy the site name and the environment. The pattern you will use for terminus commands is this:

terminus drush <sitename>.<environment> <some drush operation>

For example, if you have a project named “mywebsite” and you create a multidev named “new-theme”, then you can run a drush command against that specific environment like this:

terminus drush mywebsite.new-theme status

Here are some terminus commands and examples that are common and useful.

1. Get a list of your Pantheon projects. This will include their machine safe names.

   terminus site:list

2. Rebuild a specific site environment’s Drupal cache.

   terminus drush <site>.<env> cr

3. Clear all caches on a Drupal 7 site.

   terminus drush <site>.<env> cc all

4. Force revert all features on a Drupal 7 site.

   terminus remote:drush <site>.<env> -- fra --force -y

5. Sync a specific site environment with the configuration files.

   terminus drush <site>.<env> cim

6. Deploys code to the Test or Live environment.

   terminus env:deploy <site>.<env>

   • “Deploying the Test environment” will copy code from the Dev environment to Test.
   • “Deploying the Live environment” will copy code from the Test environment to Live.
7. Download a copy of the site environment database using drush.

   terminus remote:drush <site>.<env> -- sql-dump > backup.sql

8. Update local drush alias for Pantheon sites.

   terminus aliases

Remote Drush

Notice the fourth example listed above runs a terminus command named remote:drush and has some additional syntax. I included this example to bring up a point about what Terminus is doing behind the scenes when running drush.

If you run terminus drush <site>.<env>, terminus is actually using your local copy of drush to perform the operation on the target site environment. This can be useful sometimes, but can also get in the way.

Consider this:

• The drush utility can be extended by modules or themes installed on your Drupal site.
• You may have some modules enabled or disabled depending on the environment.
• Therefore all drush commands are not available in all environments.

Since you will need to run drush commands on all site environments, and those commands may not be available on each environment, there is a way to use terminus to execute your operation with the “remote” version of Drush. remote:drush is the terminus command that uses the version of Drush that is running on the Pantheon server.

Personally, I almost always use remote:drush for every terminus drush command.

Complicated Drush Commands

There is another caveat to know about when executing complicated drush commands with terminus. When you run terminus drush <site>.<env> <some drush operation> you have to keep in mind that you are running the terminus command on your computer, not the drush command.

This means that all the parameters and arguments you’re issuing along with that command are being captured and interpretted by terminus first. Then, after attempting to parse the parameters, terminus sends the remainder of the command to drush. So if you are attempting to issue a command or parameters to drush that look a lot like terminus commands or parameters, terminus is going to capture those commands or parameters first and try to implement them.

The way you deal with this is to always use a double dash (--) after you identify the target site environment, and before writing your drush parameters. This will tell terminus, “hey look buddy, everything after these dashes is meant for drush… you got that”? Terminus will then get scared and be sure to pass your drush parameters along to drush without trying to interpret them itself. Example:

terminus drush mysite.dev -- sqlq --db-prefix "SELECT * FROM {users}"

Combined Terminus & Drush Function – Bash

Considering the above caveats, your terminus commands should almost always follow this pattern:

terminus remote:drush <site>.<env> -- <some drush operation>

Sheesh. That can be a lot to type each time you want to run a command. Here is a simple bash function I wrote to save myself a bit of typing:

tdrush() {
  terminus remote:drush "$1" -- "${@:2:10}"
}

You can use this function by adding it to your local bash profile, then issuing terminus commands like this:

tdrush <site>.<env> sqlq --db-prefix "SELECT * FROM {users}"

Drush Aliases

Drush aliases are another way you can execute drush commands on a remote environment. This isn’t directly related to terminus, but is very similar to how terminus gives you the ability to execute drush commands on the server. The main things to know are how to get a list of aliases for your Pantheon sites, and the syntax needed to use a drush alias.

1. Have terminus automatically create your Pantheon related drush aliases.

   terminus aliases

   This will download a file to your computer which contains all the relevant Pantheon dush aliases information. It will place this new file in your local drush metadata folder. In my case, terminus placed this file at ~/.drush/pantheon.aliases.drushrc.php

2. Use a drush alias with the following syntax:

   drush @pantheon.<site>.<env> <command>

   For example:

   drush @patheon.mysite.dev cr

Since terminus remote:drush and drush aliases are very similar, generally you won’t need to use both. It’s more likely you’ll get comfortable using one of the approaches over the other and stick with it.

References:

• Drush Documentation
  • Installation
  • Git Repo
• Terminus Documentation
  • Terminus Installation
• Drupal with Composer on Pantheon