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
- type Path = ByteString
- mkPath :: [Path] -> Path
- type Revision = ByteString
- data CouchConnection
- def :: Default a => a
- couchHost :: CouchConnection -> ByteString
- couchPort :: CouchConnection -> Int
- couchManager :: CouchConnection -> Maybe Manager
- couchDB :: CouchConnection -> Path
- couchLogin :: CouchConnection -> ByteString
- couchPass :: CouchConnection -> ByteString
- class ResourceIO m => MonadCouch m where
- data CouchError = CouchError (Maybe Int) String
- runCouch :: ResourceIO m => CouchConnection -> ResourceT (ReaderT CouchConnection m) a -> m a
- withCouchConnection :: ResourceIO m => CouchConnection -> (CouchConnection -> m a) -> m a
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 = ByteStringSource
Represents a path or path fragment.
Make correct path from escaped fragments. Filter empty fragments.
mkPath ["db", "", "doc/with/slashes"] db/doc%2Fwith%2Fslashes
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.
couchHost :: CouchConnection -> ByteStringSource
Hostname. Default value is "localhost"
couchPort :: CouchConnection -> IntSource
Port. 5984 by default.
couchDB :: CouchConnection -> PathSource
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.
couchLogin :: CouchConnection -> ByteStringSource
CouchDB login. By default is empty
.
couchPass :: CouchConnection -> ByteStringSource
CouchDB password. By default is empty
.
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 whereSource
A monad which allows access to the connection.
ResourceIO m => MonadCouch (ReaderT CouchConnection m) |
data CouchError Source
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.
:: 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