Database.CouchDB.Conduit

To work with concrete objects, use the following modules:

• Database.CouchDB.Conduit.DB
• Database.CouchDB.Conduit.View
• Database.CouchDB.Conduit.Explicit
• Database.CouchDB.Conduit.Generic
• Database.CouchDB.Conduit.LowLevel

For complete documentation about The Couch DB HTTP API see http://wiki.apache.org/couchdb/Complete_HTTP_API_Reference

Document paths and revisions

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.

 database/doc%2Fname

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.

 database/_design/my%2Fdesign/_view/my%2Fview

type Path = ByteString

Represents a path or path fragment.

mkPath

Arguments

:: [Path]

Path fragments be escaped.

-> Path

Make correct path from escaped fragments. Filter empty fragments.

 mkPath ["db", "", "doc/with/slashes"]
 db/doc%2Fwith%2Fslashes

type Revision = ByteString

Represents a revision of a CouchDB Document.

CouchDB Connection

data CouchConnection

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.

Instances

Default CouchConnection

ResourceIO m => MonadCouch (ReaderT CouchConnection m)

def :: Default a => a

The default value for this type.

couchHost :: CouchConnection -> ByteString

Hostname. Default value is "localhost"

couchPort :: CouchConnection -> Int

Port. 5984 by default.

couchManager :: CouchConnection -> Maybe Manager

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

couchDB :: CouchConnection -> Path

Database name. This value is prepended to Path to form the full path in all requests.

By default is empty. This makes it possible to access different databases through a single connection. But, in this case, all requests must be preceded by the database name with unescaped slash. See Path for details.

Runtime enviroment and errors

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.

class ResourceIO m => MonadCouch m where

A monad which allows access to the connection.

Methods

couchConnection :: m CouchConnection

Instances

ResourceIO m => MonadCouch (ReaderT CouchConnection m)

data CouchError

A Couch DB Error. If the error comes from http, the http status code is also given. Non-http errors include things like errors parsing the response.

Constructors

CouchError (Maybe Int) String

Instances

Show CouchError

Typeable CouchError

Exception CouchError

runCouch

Arguments

:: 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.

withCouchConnection

Arguments

:: 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