API & Drush access to Pantheon with Terminus

I've spent more time extending terminus, and thought it would be a good time to write a little more about it.

Terminus is an API/Drush integration project, by Pantheon. At its base is an API they have exposed to access information and execute workflow functionality you would otherwise only have access to via their dashboard. Drush wraps the API and provides the shell power make for some awesome command line tools.

Some of the Drush functionality includes:

  • Clone environments
  • Download db or file backups
  • Load local db with an environment backup
  • Tunnel to mysql or redis
  • Mount an environment's file system via sshfs

Josh Koenig and Jon Peck have been active with contributions, feedback, and integrating pull requests, providing the project with some solid momentum. Be sure to check out the project and provide feedback or contribute!

Here are samples of some of the commands. In some cases, I have more detail in the pull requests linked at the bottom of each one.

1) Download Backup

This command downloads a backup to your local system.

Download the latest database backup from your site to the current directory.

$ drush psite-dl-backup sitename dev database ./

Download the latest file backup from your site to the current directory.

$ drush psite-dl-backup sitename dev files ./

Prompt support if you want to select from a different backup, or if you just forget the arguments.

$ drush psite-dl-backup
Select a site.
 [0]  :  Cancel                                                    
 [1]  :  mysitename  enterprise  site-uuid
1
Select an environment.
 [0]  :  Cancel 
 [1]  :  dev    
 [2]  :  test   
 [3]  :  live
1
Backup type.
 [0]  :  Cancel   
 [1]  :  database 
 [2]  :  files    
 [3]  :  code
1
Select a backup.
 [0]  :  Cancel                                                  
 [1]  :  mysite_dev_2013-08-26T08-00-00_database.sql.gz 7.45 MB 
 [2]  :  mysite_dev_2013-08-25T08-00-00_database.sql.gz 7.49 MB 
 [3]  :  mysite_dev_2013-08-24T08-00-00_database.sql.gz 7.64 MB 
 [4]  : mysite_dev_2013-08-24T07-01-15_database.sql.gz 7.33 MB
1
Select a destination [./]: 

pull request


2) Load Backup

This command overwrites your target database with a backup from your Pantheon site/env.

$ drush -y psite-load-backup mysitename dev latest

Targetting an alias works, but obviously in the case of a remote system, Terminus needs to be installed there as well.

$ drush -y @some.alias psite-load-backup mysitename dev latest

You will be prompted if you do not provide all the arguments.

$ drush psite-load-backup
Select a site.
 [0]  :  Cancel                                                    
 [1]  :  mysite  enterprise  site-uuid
1
Select an environment.
 [0]  :  Cancel 
 [1]  :  dev    
 [2]  :  test   
 [3]  :  live
1
Select a backup.
 [0]  :  Cancel                                                  
 [1]  :  mysite_dev_2013-08-27T08-00-00_database.sql.gz 7.53 MB 
 [2]  :  mysite_dev_2013-08-26T08-00-00_database.sql.gz 7.45 MB 
 [3]  :  mysite_dev_2013-08-25T08-00-00_database.sql.gz 7.49 MB 
 [4]  :  mysite_dev_2013-08-24T08-00-00_database.sql.gz 7.64 MB 
 [5]  :  mysite_dev_2013-08-24T07-01-15_database.sql.gz 7.33 MB
1
Overwrite this database with dev.site-uuid? (y/n): y

pull request


3) Connection Mode

This command changes the connection mode of a specific environment between git and sftp.

$ drush psite-cmode mysite dev
Connection mode: Git                                                                     [ok]
$ drush psite-cmode mysite dev sftp
Connection mode set to: SFTP                                                             [ok]

pull request


4) Tunnel

This command opens a tunnel to an environment's mysql or redis instance.

# Create tunnel to mysql
drush psite-tunnel mysite dev
# -or-
drush psite-tunnel mysite dev mysql

# Create tunnel to redis
drush psite-tunnel mysite dev redis

# Create tunnel to mysql with a local port of 4000
drush psite-tunnel mysite dev mysql 4000

# List tunnels
drush psite-tunnels

# Close all tunnels
drush psite-tclose

# Close tunnel for pid 1234  (pid is displayed when listing tunnels)
drush psite-tclose 1234

pull request & discussion


5) SSHFS Mount

This command mounts the environment's appserver to a specific destination.

$ drush psite-mount mysite dev ./some_dir

It will prompt for info and ask if the directory should be created if it doesn't exist.

$ drush psite-mount
Select a site.
 [0]  :  Cancel                                                                 
 [1]  :  mysite               enterprise  14a61510-1e81-11e3-8224-0800200c9a66 
1

Select an environment.
 [0]   :  Cancel      
 [1]   :  dev         
 [2]   :  live        
 [3]   :  test        

1
Select a mount destination: [./dev]: 
The directory ./dev does not exist.
Would you like to create it? (y/n): y
Mount successful. To unmount, run: umount ./dev                                          [ok]

$ ls dev/
cache       drushrc.php htpasswd    mime.types  php53.ini
certs       files       includes    nginx.conf  run
chef.stamp  fusedav.conf    logs        php-fpm.conf    tmp
code        fusedav_version metadata.json   php.ini

pull request