We have a new wiki. The migration is not 100% complete. You can help out by moving pages across. This wiki will exist for as long as there are pages left.

The official documentation has moved to http://docs.couchdb.org — The transition is not 100% complete, but http://docs.couchdb.org should be seen as having the latest info. In some cases, the wiki still has some more or older info on certain topics inside CouchDB.

You need to be added to the ContributorsGroup to edit the wiki. But don't worry! Just email any Mailing List or grab us on IRC and let us know your user name.

External Processes

NOTE: A much better way to do this is via the new HTTP Proxying feature. See the official documentation for that topic.

CouchDB now allows for the ability to develop custom behaviors via processes that communicate over stdin and stdout. Requests to CouchDB that are captured by the external process handler are passed via JSON object to the external process over stdin and reads a JSON object from stdout. Without further ado...

JSON Requests

Requests capture information about the incoming HTTP request and transform it into a JSON object. I've formatted the object here, though in real life this object would contain no new lines and all embedded white space would be normalized to a single ' ' (space) character.

An example object:

   1 {
   2     'body': 'undefined',
   3     'cookie': {
   4         '__utma': '96992031.3087658685658095000.1224404084.1226129950.1226169567.5',
   5         '__utmz': '96992031.1224404084.1.1.utmcsr'
   6     },
   7     'form': {},
   8     'info': {
   9         'compact_running': False,
  10         'db_name': 'couchbox',
  11         'disk_size': 50559251,
  12         'doc_count': 9706,
  13         'doc_del_count': 0,
  14         'purge_seq': 0,
  15         'update_seq': 9706},
  16     'path': [],
  17     'query': {},
  18     'method': 'GET'
  19 }

In order:

Note: Before CouchDB 0.11 method was verb.

JSON Response

The response object has five possible elements

While nothing breaks if you specify both a json and body member, it is undefined which response will be used. If you specify a Content-Type header in the headers member, it will override the default.

Common Pitfalls


Adding external processes is as easy as pie. Simply place key=command pairs in the [external] section of your local.ini and then map those handlers in the [httpd_db_handlers] section, like:

;Including [log] and [update_notification] for context

level = info

test = python /usr/local/src/couchdb/test.py

_test = {couch_httpd_external, handle_external_req, <<"test">>}

;unique notifier name=/full/path/to/exe -with "cmd line arg"

This configuration will make the /usr/local/src/couchdb/test.py responsible for handling requests from the url:${dbname}/_test

Example External Process

Here is a complete Python external process that does a whole lot of nothing except show the mechanics.

   1 import sys
   3 try:
   4     # Python 2.6
   5     import json
   6 except:
   7     # Prior to 2.6 requires simplejson
   8     import simplejson as json
  10 def requests():
  11     # 'for line in sys.stdin' won't work here
  12     line = sys.stdin.readline()
  13     while line:
  14         yield json.loads(line)
  15         line = sys.stdin.readline()
  17 def respond(code=200, data={}, headers={}):
  18     sys.stdout.write("%s\n" % json.dumps({"code": code, "json": data, "headers": headers}))
  19     sys.stdout.flush()
  21 def main():
  22     for req in requests():
  23         respond(data={"qs": req["query"]})
  25 if __name__ == "__main__":
  26     main()

A Java example can be found here: http://daily.profeth.de/2009/12/apache-couchdb-external-process-using.html

HTTP proxying

As of November 2010, Couchdb has gained the ability to manage external OS processes and to proxy to an external HTTP server.

This lets you integrate an external HTTP app server, written in any language you like, without using the JSON protocol defined above. This means you can write extensions using regular frameworks and process binary (non-UTF8, non-JSON) data. It is intended to replace the [external] mechanism.

ExternalProcesses (last edited 2013-06-05 22:15:39 by 71)