couchdb-conduit-0.7.2: Couch DB client library using http-conduit and aeson

Safe HaskellSafe-Infered





To work with concrete objects, use the following modules:

For complete documentation about The Couch DB HTTP API see


Document paths and revisions

type Path = ByteStringSource

Represents a path or path fragment.

As a rule, full path to document in CouchDB is just URL path. But there is one subtlety. For example, document ids can contain slashes. But, to work with such objects, path fragments must be escaped.


But, fo non-document items such as views, attachments e.t.c., slashes between path fragments must not be escaped. While slashes in path fragments must be escaped.


Except low-level functions, couchdb-conduit escapes all segments in paths.

type Revision = ByteStringSource

Represents a revision of a CouchDB Document.

CouchDB Connection

data CouchConnection Source

Represents a single connection to CouchDB server. The constructor for this data type is not exposed. Instead, you should use either the def method to retrieve a default instance.

def :: Default a => a

The default value for this type.

couchHost :: CouchConnection -> ByteStringSource

Hostname. Default value is "localhost"

couchPort :: CouchConnection -> IntSource

Port. 5984 by default.

couchManager :: CouchConnection -> Maybe ManagerSource

Connection Manager. Nothing by default. If you need to use your Manager (for connection pooling for example), set it to Just Manager.

couchLogin :: CouchConnection -> ByteStringSource

CouchDB login. By default is empty.

couchPass :: CouchConnection -> ByteStringSource

CouchDB password. By default is empty.

couchPrefix :: CouchConnection -> ByteStringSource

CouchDB database prefix. It will prepended to DB pathes. Must be fully valid DB name fragment.

Runtime enviroment and errors

class ResourceIO m => MonadCouch m whereSource

A monad which allows access to the connection.

All functions to access CouchDB require a MonadCouch instance to access the connection information. ReaderT is an instance of MonadCouch, and runCouch runs a sequence of database actions using ReaderT and ResourceT.

If your db code is part of a larger monad, it makes sense to just make the larger monad an instance of MonadCouch and skip the intermediate ReaderT, since then performance is improved by eliminating one monad from the final transformer stack.

data CouchError Source

A CouchDB Error.


CouchHttpError Int ByteString

Error comes from http.

CouchInternalError ByteString

Non-http errors include things like errors parsing the response.


Is not an error actually. It is thrown when CouchDB returns 304 - Not Modified response to the request. See



:: ResourceIO m 
=> CouchConnection

Couch connection

-> ResourceT (ReaderT CouchConnection m) a

CouchDB actions

-> m a 

Run a sequence of CouchDB actions. This function is a combination of withCouchConnection, runReaderT and runResourceT.

If you create your own instance of MonadCouch, use withCouchConnection.



:: ResourceIO m 
=> CouchConnection

Couch connection

-> (CouchConnection -> m a)

Function to run

-> m a 

Connect to a CouchDB server, call the supplied function, and then close the connection.

 withCouchConnection def {couchDB = "db"} . runReaderT . runResourceT $ do
    ... -- actions




:: MonadCouch m 
=> Path


-> Path

Document path.

-> ResourceT m Revision 

Get Revision of a document.



:: MonadCouch m 
=> Path


-> Path

Document path.

-> ResourceT m Revision 

Brain-free version of couchRev. If document absent, just return empty.



:: MonadCouch m 
=> Path


-> Path

Document path.

-> Revision


-> ResourceT m () 

Delete the given revision of the object.