heroku/hk — pull request #108 by bgentry (2014-02-21 06:49:31+00:00)
Title: Add pg-list command for tree list of pg databases

A common request from heavy Heroku Postgres users has been to be able to see some details about all of their databases at once, similar to the toolbelt's `heroku pg` command (or `pg:info` with no args). However, the style of that command leaves something to be desired, especially with more than two databases:

```
➜ heroku pg
=== HEROKU_POSTGRESQL_GRAY_URL
Plan: Standard Tengu
Status: Available
Data Size: 6.4 MB
Tables: 0
PG Version: 9.3.2
Connections: 3
Fork/Follow: Unavailable on followers
Rollback: from 2014-02-20 21:33 UTC
Created: 2014-02-20 19:48 UTC
Following: HEROKU_POSTGRESQL_OLIVE
Behind By: 0 commits
Maintenance: not required

=== HEROKU_POSTGRESQL_OLIVE_URL
Plan: Standard Tengu
Status: Available
Data Size: 6.4 MB
Tables: 0
PG Version: 9.3.2
Connections: 3
Fork/Follow: Available
Rollback: from 2014-02-20 21:33 UTC
Created: 2014-01-14 23:35 UTC
Followers: HEROKU_POSTGRESQL_GRAY
Forks: HEROKU_POSTGRESQL_ROSE
Maintenance: not required

=== HEROKU_POSTGRESQL_ROSE_URL
Plan: Standard Tengu
Status: Available
Data Size: 6.4 MB
Tables: 0
PG Version: 9.3.2
Connections: 3
Fork/Follow: Available
Rollback: from 2014-02-20 21:33 UTC
Created: 2014-02-20 19:47 UTC
Forked From: HEROKU_POSTGRESQL_OLIVE
Followers: HEROKU_POSTGRESQL_WHITE
Maintenance: not required

=== HEROKU_POSTGRESQL_WHITE_URL
Plan: Standard Tengu
Status: Available
Data Size: 6.4 MB
Tables: 0
PG Version: 9.3.2
Connections: 3
Fork/Follow: Unavailable on followers
Rollback: from 2014-02-20 21:33 UTC
Created: 2014-02-20 21:03 UTC
Following: HEROKU_POSTGRESQL_ROSE
Behind By: 0 commits
Maintenance: not required
```

Outputting key/value entries for multiple objects is also not inline with the style of hk. It's either simple, tabular output for a list of items, or detailed key/value output for a single item. When you look at the amount of data being shown by the command above, it's not really possible to work that into a tabular output.

For a `pg-list` command, I instead tried to focus on showing only the most important attributes. I also wanted to increase the information density of the output, making it easier for the user to picture of how their databases are related and see what state they're in.

Because Heroku Postgres databases can often have a relationship to one another (via fork or follow), I thought it would be meaningful to illustrate that relationship with a `tree` style output, rather than make the user create that map in their head.

Here's a simple example with a database and a fork of it:

```
➜ hk pg-list
heroku-postgresql-crimson* crane Available 5
└─ ─┤ heroku-postgresql-copper ronin Available !! 3
```

In this example, `heroku-postgresql-crimson` is a standalone database with a single fork (`heroku-postgresql-copper`). The `crimson` database is also set as the app's `DATABASE_URL` as denoted by the asterisk. Each database's plan, state, and connection count are listed as well. Finally, `heroku-postgresql-copper` has a scheduled maintenance event, denoted by `!!` after the status.

Here's another example which was intentionally overcomplicated and unrealistic in order to demonstrate how this works even with multiple levels of forks and followers:

```
➜ hk pg-list
heroku-postgresql-green standard-tengu Available 3
heroku-postgresql-olive* standard-tengu Available 3
├───> heroku-postgresql-gray standard-tengu Available 3
├───> heroku-postgresql-orange standard-tengu Available 3
├─ ─┤ heroku-postgresql-rose standard-tengu Available 3
│ └───> heroku-postgresql-white standard-tengu Preparing 3
└─ ─┤ heroku-postgresql-teal standard-tengu Unavailable 3
```

Here's a screenshot of how this looks in the terminal for an app with 4 databases with scheduled maintenance:

![](http://cl.ly/image/2z253A3j391v/data)

## Design iteration

I mocked up many different styles of outputs in [a gist](https://gist.github.com/bgentry/458b523b6ae600f45035) before choosing the styles shown above. I'm not set on them, though, and I'd welcome any suggestions on how to better convey this information.

## Ideas for improvement?

One suggestion from @max was to maybe indent all rows slightly, with the asterisk at the beginning denoting the database which is the `DATABASE_URL`:

```
➜ hk pg-list
heroku-postgresql-green standard-tengu Available 3
* heroku-postgresql-olive standard-tengu Available 3
```

I'm also not sure that `pg-list` is the right name for this command. I'm debating whether I should just go with `pg-tree` instead.

/cc @dpiddy @deafbybeheading @fdr as I know they've expressed some interest in this command and have given me a bit of feedback so far.