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.
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.
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 == 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 (
db:info) and remove them (
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 (
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
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 firstname.lastname@example.org if you need to use it in production sooner.