Broccoli CouchDB Versioning

A Broccoli plugin for defining CouchDB Design documents with files, and using Broccoli to keep them in sync with the database

Installation

npm install --save broccoli-couchdb-versioning

Getting Started

The input tree is expected to have the following structure:

couchdb
|--- _design
+--- docs #(optional)

The _design directory keeps your design documents, and the docs directory keeps any lookup data you want in your database.

To facilitate development, the contents of the _design directory is 'unrolled' JSON. A typical example:

_design
|--- myDesignDocument
|    |--- _rev.txt #<some rev value>
|    |--- language.txt #javascript
|    +--- views
|         +--- someViewName
|              |--- map.js #the map function for this view
|              +--- reduce.js #the optional reduce for this view
+--- myOtherDesignDocument
     |--- _rev.txt #<some rev value>
     |--- language.txt #javascript
     +--- views
          +--- someOtherViewName
               +--- map.js #the map function for this view

This makes it easier to develop and test specific map/reduce functions. CouchDBVersioning rolls this structure up into appropriately formatted design documents when updating CouchDB.

The docs directory is expected to be flat - one file per CouchDB Document. Each file is expected to be valid JSON. The file name will be the name of the document in CouchDB:

docs
+--- myDoc.json #{"foo":"bar"}

results in a CouchDB Document:

{
   "foo":"bar",
   "_id":"myDoc",
   "_rev":"some revision string"
}

Configuration

//Brocfile.js
var couchDBVersioning = require('broccoli-couchdb-versioning');

module.exports = couchdBVersioning('couchdb', {
  url:'http://localhost:5984/db',
  username:admin_username,
  password:admin_password,
  initDesign:true, //optional. Useful for initial setup
  manageDocs:true //optional. See documentation
});

• couchdb is the path to where your couchdb assets are, or should be stored
• url is the url to your database
• username is an admin usename with view read and update rights
• password is their password
• initDesign should be set to true if you want to have broccoli-couchdb-versioning load the existing CouchDB design documents database to your file system on startup. NOTE only do this once. Optional. Defaults to false.
• manageDocs whether or not the docs directory should be monitored. Optional. Defaults to true.

initDesign is useful to capture existing design documents. Set the option to true, execute broccoli build dist, and then remove it. Leaving this value set could result local changes being over-ridden when CouchDB Versioning starts.

manageDocs is useful when you have static documents to manage. If set to true, then the docs subdirectory must exist, and contain one or more JSON files. Setting manageDocs to false will speed up builds when you're actively developing views.

You can also define your configuration dynamically. One example:

//Brocfile.js
var couchDBVersioning = require('broccoli-couchdb-versioning');

// was broccoli executed as 'broccoli build ...'?
var isBuild = process.argv.indexOf('build') > -1;

module.exports = couchdBVersioning('couchdb', {
  url:'http://localhost:5984/db',
  username:admin_username,
  password:admin_password,
  manageDocs:isBuild //only manage documents during builds, not 'broccoli serve'
});

In this configuration, the developer can use broccoli serve in cases where design docs are under development, but static docs are stable. broccoli build will still manage static documents

Once you have captured your CouchDB Design documents, you can keep broccoli serve running during a development session. When you update a file, it's associated design document will get updated automatically.

Things to consider

• Synchronization is only one way - from the file system to the server. This tool assumes that the file system is always the expert.
• Deleting a design document locally will not reflect to the server. Inserts and updates will work
• broccoli-couchdb-versioning adds a revTimestamp field to each design document. It's this field that is used to determine if a document should be updated
• broccoli-couchdb-versioning will refuse to update a document if the server revTimestamp is greater than the last recorded revision. If this happens, double check with your source control or someone else in your team. broccoli-couchdb-versioning will continue to work for other documents.

Contribute

Check out broccoli-couchdb-versioning.

TODO

• Determine when a design document has been deleted, and remove it from the other store

License

MIT license.