Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 9bd4eccc8b
Fetching contributors…

Cannot retrieve contributors at this time

100 lines (64 sloc) 3.248 kb

Ping the CouchDB query server

Pingquery is a plugin to help ascertain whether the query server is working normally. It provides a new URL where an admin can submit an expression in that language, (2 + 2), and compare it to the expected output (4).

Good ping example

POST /_pingquery/javascript HTTP/1.1
Authorization: Basic <admin credentials>

{ "in" : "function() { return 'Hello world' }"
, "out": "Hello world"

HTTP/1.1 200 OK
Server: CouchDB/1.1.1 (Erlang OTP/R14B04)
Date: Fri, 09 Dec 2011 01:39:02 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 35
Cache-Control: must-revalidate

{"ok":true,"match":"Hello, world"}

Bad ping example

POST /_pingquery/javascript HTTP/1.1
Authorization: Basic <admin credentials>

{ "in" : "function() { return 'Foo' }"
, "out": "Bar"

HTTP/1.1 500 Internal Server Error
Server: CouchDB/1.1.1 (Erlang OTP/R14B04)
Date: Fri, 09 Dec 2011 01:43:34 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 75
Cache-Control: must-revalidate



I like to use cURL from a cron job to detect problems:

$ curl --silent --fail -XPOST -HContent-Type:application/json -o /dev/null \    \
       -d '{"in":"function() { return typeof log }", "out":"function"}'
$ echo $?


Pingquery works with all query server languages: JavaScript, CoffeeScript, Native (Erlang), Python, Ruby, etc.

To execute a ping, the plugin tricks the query server into running a standard _show function, then examines the output.


If you hate Freedom, just sign up for an Iris Couch account, since they run hosted CouchDB with this plugin.

To build for yourself, use Build CouchDB:

rake plugin="git:// origin/master"


Build CouchDB already took care of this step!


This is what I do. It's not perfect but barely harder than building a fork of CouchDB, and it allows 1.0.x, 1.1.x, as well as trunk support.

This example assumes three Git checkouts, side-by-side:

  • couchdb - Perhaps a trunk checkout, but could be any tag or branch
  • build-couchdb - For the boring Couch dependencies
  • pingquery_couchdb - This code

Build dependencies plus couch

Feel free to skip this if you are Randall Leeds. (Hi, Randall!)

cd couchdb
rake -f ../build-couchdb/Rakefile couchdb:configure
# Go get coffee. This builds the deps, then runs the boostrap and configure scripts
make dev

Next, teach rebar where to find CouchDB, and teach Erlang and Couch where to find this plugin.

cd ../pingquery_couchdb
export ERL_COMPILER_OPTIONS='[{i, "../couchdb/src/couchdb"}]'
export ERL_ZFLAGS="-pz $PWD/ebin"
ln -s "../../../../pingquery_couchdb/etc/couchdb/default.d/pingquery.ini" ../couchdb/etc/couchdb/default.d

You're ready. Run this every time you change the code:

./rebar compile && ../couchdb/utils/run -i
Jump to Line
Something went wrong with that request. Please try again.