NAME

    DB::CouchDB - A low level perl module for CouchDB

VERSION

0.2

RATIONALE

After working with a lot several of the CouchDB modules already in CPAN I found myself dissatisfied with them. Since the API for Couch is so easy I wrote my own which I find to have an API that better fits a CouchDB Workflow.

SYNOPSIS

    my $db = DB::CouchDB->new(host => $host,
                              db   => $dbname);
    my $doc = $db->get_doc($docname);
    my $docid = $doc->{_id};

    my $doc_iterator = $db->view('foo/bar', \%view_query_opts);

    while ( my $result = $doc_iterator->next() ) {
        ... #do whatever with the result the view returns
    }

METHODS

new(%dbopts)

This is the constructor for the DB::CouchDB object. It expects a list of name value pairs for the options to the CouchDB database.

Required options: (host => $hostname, db => $database_name);
Optional options: (port => $db_port)

Accessors

host - host name of db
db - database name
port - port number of the database server
json - the JSON object for serialization

handle_blessed

Turns on or off the JSON's handling of blessed objects.

    $db->handle_blessed(1) #turn on blessed object handling
    $db->handle_blessed() #turn off blessed object handling

all_dbs

    my $dbs = $db->all_dbs() #returns an arrayref of databases on this server

all_docs

    my $dbs = $db->all_dbs() #returns a DB::CouchDB::Iterator of
                             #all documents in this database

db_info

    my $dbinfo = $db->db_info() #returns a DB::CouchDB::Result with the db info

create_db

Creates the database in the CouchDB server.

    my $result = $db->create_db() #returns a DB::CouchDB::Result object

delete_db

deletes the database in the CouchDB server

    my $result = $db->delete_db() #returns a DB::CouchDB::Result object

create_doc

creates a doc in the database. The document will have an automatically assigned id/name.

    my $result = $db->create_doc($doc) #returns a DB::CouchDB::Result object

temp_view

runs a temporary view.

    my $results = $db->temp_view($view_object);

create_named_doc

creates a doc in the database, the document will have the id/name you specified

    my $result = $db->create_named_doc($doc, $docname) #returns a DB::CouchDB::Result object

update_doc

Updates a doc in the database.

    my $result = $db->update_doc($docname, $doc) #returns a DB::CouchDB::Result object

delete_doc

Deletes a doc in the database. you must supply a rev parameter to represent the revision of the doc you are updating. If the revision is not the current revision of the doc the update will fail.

    my $result = $db->delete_doc($docname, $rev) #returns a DB::CouchDB::Result object

get_doc

Gets a doc in the database.

    my $result = $db->get_doc($docname) #returns a DB::CouchDB::Result object

view

Returns a views results from the database.

    my $rs = $db->view($viewname, \%view_args) #returns a DB::CouchDB::Iter object

A note about view args:

the view args allow you to constrain and/or window the results that the view gives back. Some of the ones you will probably want to use are:

    group => "true"      #turn on the reduce portion of your view
    key   => '"keyname"' # only gives back results with a certain key
    
    #only return results starting at startkey and goint up to endkey
    startkey => '"startkey"',
    endkey   => '"endkey"'

    count => $num  #only returns $num rows
    offset => $num #return starting from $num row

All the values should be valid json encoded. See http://wiki.apache.org/couchdb/HttpViewApi for more information on the view parameters

AUTHOR

Jeremy Wall <jeremy@marzhillstudios.com>

CPAN RT