Lenz Gschwendtner > Store-CouchDB > Store::CouchDB



Annotate this POD


New  1
Open  0
View/Report Bugs
Module Version: 2.8   Source  


Store::CouchDB - a simple CouchDB driver




Store::CouchDB is a very thin wrapper around CouchDB. It is essentially a set of calls I use in production and is by no means a complete library, it is just complete enough for the things I need to do. This is a grown set of functions that evolved over the last years of using CouchDB in various projects and was written originally to be compatible with DB::CouchDB. This has long passed and can only be noticed at some places.

One of the things I banged my head against for some time is non UTF8 stuff that somehow enters the system and then breaks CouchDB. I use the brilliant Encoding::FixLatin module to fix this on the fly.

    use Store::CouchDB;

    my $db = Store::CouchDB->new();
    $db->config({host => 'localhost', db => 'your_db'});
    my $couch = {
        view   => 'design_doc/view',
        opts   => { key => '"' . $key . '"' },
    my $status = $db->get_array_view($couch);



The Store::CouchDB class takes a number of parameters:


Sets the class in debug mode


The host to use. Defaults to 'localhost'


The port to use. Defaults to '5984'


Connect to host via SSL/TLS. Defaults to '0'


The DB to use. This has to be set for all oprations!


The DB user to authenticate as. optional


The password for the user to authenticate with. required if user is given.


This is internal and sets the request method to be used (GET|POST)


This is set if an error has occured and can be called to get the last error with the 'has_error' predicate.



How many documents shall we try to purge. Defaults to 5000


The get_doc call returns a document by its ID

    get_doc({id => DOCUMENT_ID, [dbname => DATABASE]})


If all you need is the revision a HEAD call is enough.


The get_design_docs call returns all design document names in an array reference.

    get_design_docs({[dbname => DATABASE]})


The put_doc call writes a document to the database and either updates a existing document if the _id field is present or writes a new one. Updates can also be done with the update_doc call but that is really just a wrapper for put_doc.

    put_doc({doc => DOCUMENT, [dbname => DATABASE]})


The del_doc call marks a document as deleted. CouchDB needs a revision to delete a document which is good for security but is not practical for me in some situations. If no revision is supplied del_doc will get the document, find the latest revision and delete the document.

    del_doc({id => DOCUMENT_ID, [rev => REVISION, dbname => DATABASE]})


The update_doc function is really just a wrapper for the put_doc call and mainly there for compatibility. the naming is different and it is discouraged to use and may disappear in a later version.

    update_doc({doc => DOCUMENT, [name => DOCUMENT_ID, dbname => DATABASE]})


The copy_doc is _not_ the same as the CouchDB equivalent. In CouchDB the copy command wants to have a name/id for the new document which is mandatory and can not be ommitted. I find that inconvenient and made this small wrapper. All it does is getting the doc to copy, removes the _id and _rev fields and saves it back as a new document.

    copy_doc({id => DOCUMENT_ID, [dbname => DATABASE]})


There are several ways to represent the result of a view and various ways to query for a view. All the views support parameters but there are different functions for GET/POST view handling and representing the reults. The get_view uses GET to call the view and returns a hash with the _id as the key and the document as a value in the hash structure. This is handy for getting a hash structure for several documents in the DB.

           view => 'DESIGN_DOC/VIEW',
           opts => { key => "\"" . KEY . "\"" }


The get_post_view uses POST to call the view and returns a hash with the _id as the key and the document as a value in the hash structure. This is handy for getting a hash structure for several documents in the DB.

           view => 'DESIGN_DOC/VIEW',
           opts => [ KEY1, KEY2, KEY3, ... ]


Same as get_array_view only returns a real array. Use either one depending on your use case and convenience.


The get_array_view uses GET to call the view and returns an array reference of matched documents. This view functions is the one I use most and has the best support for corner cases.

           view => 'DESIGN_DOC/VIEW',
           opts => { key => "\"" . KEY . "\"" }

A normal response hash would be the "value" part of the document with the _id moved in as "id". If the response is not a HASH (the request was resulting in key/value pairs) the entire doc is returned resulting in a hash of key/value/id per document.


This function tries to find deleted documents via the _changes call and then purges as many deleted documents as defined in $self->purge_limit which currently defaults to 5000. This call is somewhat experimental in the moment.

    purge({[dbname => DATABASE]})


This compacts the DB file and optionally calls purge and cleans up the view index as well.

    compact({[purge=>1, view_compact=>1]})


To add an attachement to CouchDB use the put_file method. 'file' because it is shorter than attachement and less prone to misspellings. The put_file method works like the put_doc function and will add an attachement to an existing doc if the '_id' parameter is given or addes a new doc with the attachement if no '_id' parameter is given. The only mandatory parameter is the 'file' parameter.


Get a file attachement from a CouchDB document.


This can be called with a hash of config values to configure the databse object. I use it frequently with sections of config files.

    config({[host => HOST, port => PORT, db => DATABASE]})


Create a Couch



Nothing is exported at this stage.


Lenz Gschwendtner, <norbu09 at cpan.org>


Please report any bugs or feature requests to bug-store-couchdb at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Store-CouchDB. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc Store::CouchDB

You can also look for information at:


Thanks for DB::CouchDB which was very enspiring for writing this library


Copyright 2010 Lenz Gschwendtner.

This program is free software; you can redistribute it and/or modify it under the terms of either: the Apache License or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

syntax highlighting: