A Power Tool for DevOps - the MongoHQ CLI

When we recently released the new API, we knew that it wouldn't just be programmers who'd want to tap into its flexibility and power to control and manage MongoHQ database deployments. Thats why we've also been working on a command line interface too which brings that same power and flexibility to your terminal's prompt and we are releasing the beta version of that tool today. mongohq the command, is a swiss army knife of functionality which maps the MongoHQ API into easy to use commands.

CLI Quickstart

The mongohq command has help for all its commands built in and running it with no parameters will present a guide to all the available options. There's sets of commands for accounts, users, backups, databases and deployments along with specific commands for browsing logs, getting database statistics and getting a realtime view of mongostat – a first port of call when analysing performance issues. We prefer to show rather than tell so here's a brief session with the command. First up, we can list the deployments associated with the account:

$ mongohq deployments
== My Deployments
production  
development  
stuntcar  

Here we can see three Elastic Deployments, one for production, one for development and one we call the stuntcar. These are user set deployment names. If you have older deployments, they may not be named and will show their hex identifier. You can use mongohq deployments:rename to set a readable name. If you want to find out more about a deployment you can use mongohq deployments:info like so:

$ mongohq deployments:info --deployments stuntcar
== stuntcar
 name            : stuntcar
 plan            : mongohq:elastic
 status          : running
 location        : aws:eu-west-1
 current primary : lamppost.3.mongolayer.com:10089
 members         : lamppost.3.mongolayer.com:10089,lamppost.2.mongolayer.com:10089
 version         : 2.6.3
  == Databases
    notes
    documents

So here we have two databases in the deployment which is running MongoDB 2.6.3. We can shorten deployments to dep in commands and parameters so mongohq dep:info --dep stuntcar is a shorter equivalent form. Now we know what databases are in the deployment, let's add one:

$ mongohq databases:create --dep stuntcar --database customers
== customers
 status     :running
 deployment :stuntcar

Like "deployments", databases can also be shortened to db so we could have run mongohq db:create -dep stuntcar --db customers. Once we've created a database, we can add a user to it with mongohq users:create and we now have a MongoDB database ready to run. We can also list users and remove users so you can automate your user management.

Further features

If we want to make a new deployment and database in one step, there's the deployments:create command which takes names for a new deployment and database and a location for where that new deployment should be created. To find available locations, you can run mongohq locations...

$ mongohq locations
== locations
  aws:ap-southeast-2
  aws:eu-west-1
  aws:us-east-1
  aws:us-west-2
  digital-ocean:nyc2
  gogrid:us-west-1
  mongohq:us-east-1
  softlayer:dallas-05

This also shows how a location is made up of a cloud provider and geographical location. As well as creating databases and deployments, it logically follows that you can also get information about them (dep:info and db:info) and remove them (dep:remove and db:remove). The CLI also gives you control of your backups so you can create on-demand backups (backups:create), list your available backups (backups), get information on a specific backup (backups:info) and restore a backup (backups:restore).

But there's more. The logs command gives you not just a way to view the logs but to page through and use regular expressions to filter your logs so you can home in on the information you want. If you want raw statistics then the mongostats command can plug you into a realtime stream of them from any deployment, including insert, query, update and delete rates, memory use, faults, locking and network traffic for all the instances in the replica set.

Now you may not want to be typing mongohq all the time, so we've also added a shell mode which give you a dedicated command line with history and tab completion for commands.

Getting the CLI

Hopefully, you're already looking forward to using the mongohq command. You can get the installable binary by running:

curl https://mongohq-cli.s3.amazonaws.com/install.sh | sh  

When you run it for the first time, it will take you through an authenticaton process which will store a token in your home directory – if you want to dispose of that token after a session, run mongohq logout.

If you aren't keen on running scripts from the internet but are happy to download and run the binary, you can download the script and follow its steps to install. As with any Swiss Army knife, you'll want the opportunity to check all the blades for safety, so we've also made mongohq-cli open source so you can assure yourself of its usefulness. If you're into coding, especially in Go as thats what mongohq-cli is written in, we also encourage you to enhance it - we will happily take pull requests for fixes and features.

You can find all the details of the new CLI on the CLI Getting Started page. The current release is a beta version and is subject to change – do contact support@mongohq.com if you need to use it in production sooner.