Command-line tools for Cloudant and CouchDB

Some developers spend their days dragging and dropping in a graphical user interface, others are more comfortable typing green letters into a black background on a command-line terminal. If you are the latter type of developer, then this blog post is for you. We introduce a range of command-line tools that you can use to interface with IBM Cloudant (or plain Apache® CouchDB™).

Cloudant and CouchDB share an RESTful HTTP API allowing access from any programming language or from the command-line using the curl utility. The packages featured in this blog post are all free to download and open-source, allowing you to fork and modify them for your own purposes.

ccurl

Most Cloudant and CouchDB developers use curl to access the RESTful HTTP API. The trouble with curl is that the commands can get overly long, with lots of repetition between commands, for example:

jq

Simplify dealing with JSON on the command line by installing the jq utility, which parses and filters JSON strings. In this example, jq takes the stream of data coming from ccurl, and turns it into nicely formatted, coloured terminal output:

ccurl /mydb/12345 | jq .

You can supply arguments to the jq command. For example:

ccurl /mydb/12345 | jq .geometry.coordinates

fetches the coordinates from the geometry object included within the JSON object returned by the ccurl command. jq has its own syntax that allows JSON objects to be filtered, manipulated and queried. See the jq website for further details.

couchshell

If you’re familiar with the file and directory commands of a Unix shell, then you should find couchshell intuitive to use. It presents a Cloudant account or CouchDB installation as a directory tree, with top-level directories being databases, and their contents being documents. It uses the same environment variable as ccurl and can be invoked by typing couchshell. The result is you find yourself in a shell-like environment, with a >> prompt. The environment is optimized for working with Couch and Cloudant commands with “tab autocomplete” of database names and document ids:

The above sequence of commands creates a database, creates two documents, and deletes one of them.

A full list of the couchshell commands is provided on the tool’s website.

couchimport

If you have CSV files containing data which you need to upload to Cloudant or CouchDB, then couchimport can import the files. The following sequence of shell commands download a dataset containing US crime data, unzip it, creates a new CouchDB database, and finally imports the CSV data by piping the file to the couchimport:

Once again, couchimport uses the same COUCH_URL environment variable to determine the database to write to. couchimport can also be used programmatically to allow your Node.js applications to import CSV files or streams into CouchDB or Cloudant.

couchbackup

If you need to backup and restore CouchDB data, then couchbackup and couchrestore utilities can help. Backup is as simple as running the couchbackup; in this case taking a copy of the animals database and saving it to the file animals.txt:

couchbackup --db animals > animals.txt

Restoring a backup is the reverse operation – pipe the file to couchrestore:

couchmigrate

When changing a database’s design documents, you need to take care that users of the database don’t suffer performance issues as the new index rebuilds. The couchmigrate utility creates a new design document, waits for the index to build, and finally makes the index live.

For example, if our new design document is in a file dd.json, we could run the following command:

couchmigrate --dd dd.json --db movies

This command blocks use until the views defined in dd.json are ready to use.

Before joining IBM Cloud Data Services, Glynn served as the Head of IT and Development for Central Index, creating a white-label frontend for a NoSQL business directory (using PHP, Node.js, MySQL, Redis, Cloudant, and Redshift). His experience includes writing CRM systems, "find my nearest" indexes, e-commerce platforms, and a phone tracking app. He also built a transport route-planning system in Java. Glynn got his start in Research and Development for the steel industry, creating control and instrumentation systems. Outside work, Glynn enjoys guitars, football, crosswords, and Victorian fiction.