couchxray

couchxray is a command-line tool which outputs the CouchDB features used by a database and was inspired by the Python project xray by Will Holley. On a per database basis, couchxray outputs whether it is using:

global MapReduce views and which reducers (built-in or bespoke) are being used.
Lucene-based search indexes or Cloudant-specific Geospatial indexes.
so called "Mango" (aka Cloudant Query) indexes backed by MapReduce or Lucene.
partitions, and which form of per-partition secondary indexes are used.
CouchDB features such as update/show/list/vdu functions.
dbcopy, a now-deprecated Cloudant-only feature.

This information is useful when moving data between major versions of CouchDB. couchxray outputs a "compatibility" object which shows which versions of CouchDB are suitable for hosting the database e.g. if the database is using Lucene-based indexes then CouchDB 3+ would be required.

The tool outputs data in JSON for single-database requests or as a CSV when profiling all the databases in a CouchDB instance.

Installation

Installation requires Node.js/npm to be installed:

npm install -g couchxray

Usage

The URL containing the CouchDB service, including service credentials, should be supplied as a COUCH_URL environment variable or as the only command-line parameter.

e.g.

> export COUCH_URL="https://username:password@host.cloudant.com"
> couchxray

export COUCH_URL="https://username:password@host.cloudant.com"
couchxray cities

couchxray "https://username:password@host.cloudant.com"

couchxray "https://username:password@host.cloudant.com/cities"

Examining a single database

If the URL supplied contains the database name, a single database is examined and the output data is presented as JSON.

> couchxray http://admin:admin@localhost:5984/cities
{
  "databaseName": "cities",
  "partitioned": false,
  "numDocs": 23514,
  "numDeletions": 9,
  "numDesignDocs": 8,
  "totalDocs": 23531,
  "diskSize": 13688612,
  "billableSize": 2683923,
  "q": 16,
  "recommendedQDocs": 1,
  "recommendedQBytes": 1,
  "indexes": {
    "global": {
      "mapReduce": 7,
      "search": 1,
      "geo": 0,
      "mangoJSON": 0,
      "mangoText": 0
    },
    "partitioned": {
      "mapReduce": 0,
      "search": 0,
      "mangoJSON": 0,
      "mangoText": 0
    },
    "viewGroups": {
      "mapReduce": 8,
      "search": 1,
      "mango": 0
    },
    "updates": 0,
    "shows": 0,
    "lists": 0,
    "vdus": 0,
    "dbcopy": 0,
    "reducers": {
      "_count": 2,
      "_sum": 4,
      "_stats": 1,
      "_approx_count_distinct": 0,
      "none": 0,
      "custom": 0
    }
  },
  "compatibility": {
    "couchDB1": {
      "ok": false,
      "features": [
        "search"
      ]
    },
    "couchDB2": {
      "ok": false,
      "features": [
        "search"
      ]
    },
    "couchDB3": {
      "ok": true
    },
    "couchDB4": {
      "ok": true
    }
  }
}

Examining all databases

If the URL points to the "top level" of the CouchDB service, all of the databases are examined and the output data is presented as a CSV file:

> couchxray http://admin:admin@localhost:5984
databaseName,partitioned,numDocs,numDeletions,numDesignDocs,totalDocs,diskSize,billableSize,q,recommendedQDocs,recommendedQBytes,indexes.global.mapReduce,indexes.global.search,indexes.global.geo,indexes.global.mangoJSON,indexes.global.mangoText,indexes.partitioned.mapReduce,indexes.partitioned.search,indexes.partitioned.mangoJSON,indexes.partitioned.mangoText,indexes.viewGroups.mapReduce,indexes.viewGroups.search,indexes.viewGroups.mango,indexes.updates,indexes.shows,indexes.lists,indexes.vdus,indexes.dbcopy,indexes.reducers._count,indexes.reducers._sum,indexes.reducers._stats,indexes.reducers._approx_count_distinct,indexes.reducers.none,indexes.reducers.custom,compatibility.couchDB1.ok,compatibility.couchDB2.ok,compatibility.couchDB3.ok,compatibility.couchDB4.ok
aaa,false,3,1,1,5,388179,173,16,1,1,1,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,1,0,true,true,true,true
aa,false,2,0,0,2,2722750,2489192,16,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,true,true,true,true
a,false,22,3,2,27,4353575,250017,16,1,1,0,0,0,1,1,0,0,0,0,0,0,2,0,0,0,0,0,1,0,0,0,0,0,false,mango,true,true,true
_replicator,false,4,22,1,27,2297477,14447,16,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,true,true,true,true
a1,false,1,0,0,1,154619,39,16,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,true,true,true,true
ab,false,3,0,1,4,388147,387,16,1,1,1,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,1,0,0,0,0,true,true,true,true
abb,false,1,0,0,1,154507,20,16,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,true,true,true,true

What does the output data mean?