Clippan CouchDB cli

Posted on Jul 24, 2022

I love CouchDB. To me it’s a simple, easy to understand document store with predictable, reliable master-master synchronization/replication and, when needed, high availability. And it can easily be extended beyond basic use cases through views. It can be fully controlled and used using regular HTTP (REST) requests

It also has a fantastic web based admin interface, “Fauxton”.

However, it doesn’t really have a cli (beyond using curl with some tricks). So I wrote one: clippan. The name is a bit of a pun on Couches, IKEA and Kivik, a fantastic CouchDB adapter for Go written by Jonathan Hall

(not sure if reCLIner would have been a better pun, but I’ll stick with clippan for now)

Goals

The first goals are to do basic tasks through a simple but user friendly cli, e.g.

create, list, select and delete databases
create, edit documents (including design docs)
query views (with optional reduce), list/show documents

It can currently do most of these tasks already.

Later, it should also be able to do more higher level tasks such as

manage access control
configuration, tuning
replication

and perhaps, at some point,

run some (lua?) update script on a set of matching documents

Sample session

$ clippan -write
Connecting to http://admin:xxxx@localhost:5984
localhost:5984> createdb sample_session

localhost:5984/sample_session(rw)> put doc1
Creating doc1

    (creating doc with typo in $EDITOR)

{"_id": doc1",
        ^-invalid character 'd' looking for beginning of value
"value": 42}
Document does not validate as json. (E)dit again or (A)bort?>

    (fixing and saving doc)

Document saved with revision 1-a39def32b27fca87dea9b3da001b496b

localhost:5984/sample_session(rw)> get doc1
{
  "_id": "doc1",
  "_rev": "1-a39def32b27fca87dea9b3da001b496b",
  "value": 42
}

localhost:5984/sample_session(rw)> all
doc1 doc1 {"rev":"1-a39def32b27fca87dea9b3da001b496b"}

localhost:5984/sample_session(rw)> deletedb sample_session
Please type sample_session to delete it> sample_session
Unselecting database before destroying
Database sample_session destroyed

localhost:5984> help
use                   Connect to a database (takes just a database name or a full dsn)
databases             List all databases
createdb              Create a database (w)
deletedb              Delete a database (w)
all                   List all docs, paginated
get                   Get a single document by id
put                   Create a new document (w)
edit                  Edit an existing document (w)
query                 Query a view
exit                  Exit clippan
help                  Show help

Use <cmd> -h to get additional options for that command