0.3.5 • Public • Published


A command-line tool to assist with the migration of CouchDB Design Documnents


npm install -g couchmigrate


Create a JSON file with your design document in e.g. dd.json

    "_id": "_design/fetch",
    "views": {
        "byx": {
            "map": "function (doc) {\n  emit(doc.x, doc.y);\n  }",
            "reduce": "_stats"
    "language": "javascript"

or a JavaScript file that exports a design document object e.g.

var map = function(doc) {
  emit(, null);

module.exports = {
  _id: "_design/testy",
  views: {
    test1: {
      map: map.toString(),
      reduce: "_count"

Then setup environment variables to point to your instance of CouchDB

export COUCH_URL=


export COUCH_URL=

Then run couchmigrate:

couchmigrate --dd dd.json --db mydatabase
  • dd - the path to the file containing the design documnet
  • db - the name of the database

(if the file extension of dd is '.json', it is expected to be a JSON document, if it ends in '.js' it is expected to be a JavaScript file that can be required in)

If the design document is already present and is identical to the one in the file, no migration will occur, otherwise

  • copy old design document to _OLD
  • import new design document to _NEW
  • trigger the view to make sure it builds
  • poll the view to see if it has finished building
  • copy _NEW to the real design document name
  • delete _NEW
  • delete _OLD
  • exit

In other words, couchmigrate will only return when the design document has been uploaded, built and has been moved into place.

IAM Auth

Alternatively, if you are using IAM authentication with IBM Cloudant, then supply two environment variables:

  • COUCH_URL - the URL of your Cloudant host e.g. (note absence of username and password in URL).
  • IAM_API_KEY - the IAM API KEY e.g. ABC123515-151215.

Package Sidebar


npm i couchmigrate

Weekly Downloads






Unpacked Size

22.5 kB

Total Files


Last publish


  • glynnbird