Database.CouchDB.Conduit

CouchDB

To work with concrete objects, use the following modules:

• Database.CouchDB.Conduit.DB Database
• Database.CouchDB.Conduit.View Views
• Database.CouchDB.Conduit.LowLevel Low-level methods

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

Document paths and revisions

type Path = ByteString

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.

 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

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

type Revision = ByteString

Represents a revision of a CouchDB Document.

mkPath

Arguments

:: [Path]

Path fragments be escaped.

-> Path

Make correct path and escape fragments. Filter empty fragments.

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

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

(MonadResource (ReaderT (Manager, CouchConnection) m), MonadBaseControl IO (ReaderT (Manager, CouchConnection) m), MonadResource m, MonadBaseControl IO m) => MonadCouch (ReaderT (Manager, 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.

couchLogin :: CouchConnection -> ByteString

CouchDB login. By default is empty.

couchPass :: CouchConnection -> ByteString

CouchDB password. By default is empty.

couchPrefix :: CouchConnection -> ByteString

CouchDB database prefix. It will prepended to first fragment of request path. Must be fully valid DB name fragment.

Runtime enviroment and errors

class (MonadResource m, MonadBaseControl IO m) => MonadCouch m where

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.

Methods

couchConnection :: m (Manager, CouchConnection)

Instances

(MonadResource (ReaderT (Manager, CouchConnection) m), MonadBaseControl IO (ReaderT (Manager, CouchConnection) m), MonadResource m, MonadBaseControl IO m) => MonadCouch (ReaderT (Manager, CouchConnection) m)

data CouchError

A CouchDB Error.

Constructors

CouchHttpError Int ByteString

Error comes from http.

CouchInternalError ByteString

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

NotModified

Is not an error actually. It is thrown when CouchDB returns 304 - Not Modified response to the request. See http://wiki.apache.org/couchdb/HTTP_Document_API

Instances

Show CouchError

Typeable CouchError

Exception CouchError

runCouch

Arguments

:: MonadResourceBase m

=> CouchConnection

Couch connection

-> ReaderT (Manager, CouchConnection) (ResourceT m) a

Actions

-> m a

Connect to a CouchDB server, run a sequence of CouchDB actions, and then close the connection.. This function is a combination of withManager, withCouchConnection, runReaderT and runResourceT.

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

withCouchConnection

Arguments

:: (MonadResource m, MonadBaseControl IO m)

=> Manager

Connection manager

-> CouchConnection

Couch connection

-> ((Manager, CouchConnection) -> m a)

Actions

-> m a

Run a sequence of CouchDB actions with provided Manager and CouchConnection.

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

Documents

couchRev

Arguments

:: MonadCouch m

=> Path

Database.

-> Path

Document path.

-> m Revision

Get Revision of a document.

couchRev'

Arguments

:: MonadCouch m

=> Path

Database.

-> Path

Document path.

-> m Revision

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

couchDelete

Arguments

:: MonadCouch m

=> Path

Database.

-> Path

Document path.

-> Revision

Revision

-> m ()

Delete the given revision of the object.