/ 
DB-CouchDB-Schema-0.2.1_fix_pod_1
River stage zero No dependents
/ DB::CouchDB

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

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>

DEPENDENCIES

SEE ALSO