[nano] Implement Support for Document Update Handlers

[twilson63]

Hello,

I would like to implement support for CouchDb Document Update Handlers.

http://wiki.apache.org/couchdb/Document_Update_Handlers

My thoughts are implementing a new function called update_doc:

   /*
    * calls document update handler
    *
    * @param {design_name:string} design document namd
    * @param {update_name:string} update method to call
    * @param {doc_name:string} document name to update
    * @param {params:object} additions to the querystring
   */   
  function update_doc(design_name, update_name, doc_name, params, callback) {
     if(typeof params === "function") {
       callback = params;
       params = {};
     }
     var update_path = '_design/' + design_name + '/_update/' + update_name + '/' + doc_name;
     return relax({db: db_name, path: update_path, method: "PUT", params: params}, callback);
   }

Then a public db alias called "update"

  public_functions.update = update_doc;

usage

This should provide the ability to easily execute atomic updates on the couchdb server:

Document Update Handler in Design Document called my_design_doc:

"updates": {
  "in-place" : "function(doc, req) {
      var field = req.query.field;
      var value = req.query.value;
      var message = 'set '+field+' to '+value;
      doc[field] = value;
      return [doc, message];
  }"
}

Then using nano:

@db.update("my_design_doc", "in-place", "<doc_name>", { field: "foo", value: "bar" }, function(e,b) { console.log(b); }); 

Thoughts?

[dscape]

Personally I like it and think it makes a lot of sense. I just don't know if the name update is appropriate. I would agree it is but I'm afraid it will make people miss understand the function.

Can you make a pull request that includes necessary tests? I know tests suck right now but I didn't have enough time to port them to Mocha yet! :)

Then a blog post introducing this would be great. Version should be 1.2.x since it's an API change.

Anyone else would like to add opinions? @perezd @pgte @mikeal @PatrickHeneise ?

[dscape]

Oh and btw, thank you. This is the kind of collaboration that makes everyone love open source :)

Welcome to the nano team! ;)

[PatrickHeneise]

At the moment I'm using the add-Handler to update documents. An update-Handler certainly makes sense! Great work, thanks!

[perezd]

I think emphasizing design docs (ie: not relying on generic terminology such as update) is important. My 2 cents!

[dscape]

@perezd how do you think the interface should look like?

[perezd]

Oh wow, I totally didn't know about this feature, I thought this was a validate_doc_update design doc thing.

[dscape]

:) Still what do you think the interface should be? Just update?

[dscape]

Btw since we are all kind of here, I've added a samples directory to nano.

Feel free to populate with common cookbook style examples so people can get started faster.

[perezd]

updateWithHandler?

[twilson63]

Cool,

I will create a pull request w/tests and name the public interface name "updateWithHandler" and the private function "update_doc_with_handler"? Sound Good?

[dscape]

@twilson63 yes!

Imho you should make the name update though. I don't see enough reason not too, since no one complained too much or shouted at me too much.

I think simplicity should prevail.

Your call! :)

[perezd]

prepared to be shouted at :)

there is no such thing as an "UPDATE" in couchDB. the PUT verb, is used for atomic saves, and all changes are atomically versioned, and unique. We have no notion of "updating a key" or things of this nature. So I think its useful to make sure that lexicon is carefully guarded.

[dscape]

updateWithHandler it is ;)

[twilson63]

How does this post look, please suggest changes/modifications...

http://jackhq.tumblr.com/post/16035106690/nano-v1-2-x-document-update-handler-support-v1-2-x

[pfiled]

Be aware, it is still possible to get conflicts. A document update handler is like a really fast client, it does not change how couchdb works:

http://stackoverflow.com/questions/2983220/can-a-couchdb-document-update-handler-get-an-update-conflict

[twilson63]

Hey Daniel,

Thanks for the heads up, we will continue to test and benchmark, but the
document handlers have definitely made a huge difference, compared to view
-> put. When calling a view then updating a document, the view would
return the same document for several hundred milliseconds. With document
handlers, the view may not be instant but it is definitely updated by 100ms.

Do you have any other suggestions?

Thanks

Tom

On Wed, Jan 18, 2012 at 12:11 AM, Daniel Pfile <
reply@reply.github.com

wrote:

Be aware, it is still possible to get conflicts. A document update handler
is like a really fast client, it does not change how couchdb works:

http://stackoverflow.com/questions/2983220/can-a-couchdb-document-update-handler-get-an-update-conflict

---

Reply to this email directly or view it on GitHub:
#50 (comment)

Tom Wilson
Jack Russell Software Company LLC
1067 Cliffwood Drive
Mount Pleasant, SC 29464
Phone: 843-606-0637
Email: tom@jackhq.com
Web: http://www.jackhq.com
Calendar: http://www.jackhq.com/calendar

[dscape]

@pfiled While that is useful information it doesn't relate much to nano.

If you guys are concerned I would suggest adding a sample to the samples/ directory, which includes conflict detection.

[mark-hahn]

I need to use body data with updateWithHandler. My data can be arbitrarily large so it cannot go into the url. I can fork it for now to get what I need but is there some reason it was not set up as body data in the first place? I can think of no reason to not always use the body.

[twilson63]

@mark-hahn just an oversight, when I implemented it, I was not sending body data, so I did not include that use case.

[mark-hahn]

It would be cool if params in relax had an option such as _httpBody. Then
if _httpBody exists it would always use that instead of opts.body. This
way one could always choose whether to use a query string or body right at
the nano call.

[dscape]

please gist me some code to see what this would mean

nice new avatar @perezd

[mark-hahn]

My code is unfortunately proprietary. Are you looking for an explanation
of why someone would want to use body data instead of query data, or for
the how?

The why is simple. My framework supports updating a doc with an
arbitrarily large amount of data which couldn't fit in a url. I use a
general purpose update handler for every Create and Update operation (from
CRUD).

Off the top of my head the how would be ...

db.updateWithHandler 'design', 'update', id, { _httpBody: bodydata}, (err,
resp, hdrs) ->

I don't know nano very well, so I couldn't say whether this would be useful
for other operations that are url-only at the moment.

I've got everything working here by patching updateWithHandler to send an
opts.body to relax(). It was amazing at how quickly I replaced my old crap
with nano. It just worked. I especially like piping attachments.

[dscape]

I meant the patch, have no interest in your application code :)

I want to understand how big of a change this is, if it means an api change, if it's relevant (the relax method is always there and can be used for uncommon operations, the updatehandler is already uncommon to start with)

[dscape]

Thanks for the compliment, but most of the credit for that goes to @mikeal for request :)

[mark-hahn]

I think you (we, I) should just switch the updatehandler call to use the
body. This would be backwards compatible. This could be done for all
other public calls that have this problem, if any. If you want a pull
request let me know. Even the tests wouldn't change.

[dscape]

Sounds good, those were my concerns.

Pull request is welcome!