GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Store::CouchDB(3) User Contributed Perl Documentation Store::CouchDB(3)

Store::CouchDB - Store::CouchDB - a simple CouchDB driver

version 4.3

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.

Refer to the CouchDB Documentation at: <http://docs.couchdb.org/en/latest/>

    use Store::CouchDB;

    my $sc = Store::CouchDB->new(host => 'localhost', db => 'your_db');
    # OR
    my $sc = Store::CouchDB->new();
    $sc->config({host => 'localhost', db => 'your_db'});
    my $array_ref = $db->get_array_view({
        view   => 'design_doc/view_name',
        opts   => { key => $key },
    });

Sets the class in debug mode

Default: false

Default: localhost

Default: 5984

Connect to host using SSL/TLS.

Default: false

The database name to use.

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)

Default: GET

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

    $sc->has_error

Error string if there was an error

How many documents shall we try to purge.

Default: 5000

Timeout in seconds for each HTTP request. Passed onto LWP::UserAgent. In case of a view or list related query where the view has not been updated in a long time this will timeout and a new request with the "stale" option set to "update_after" will be made to avoid blocking. See http://docs.couchdb.org/en/latest/api/ddoc/views.html

Set this very high if you don't want stale results.

Default: 30

The Store::CouchDB class takes a any of the attributes described above as parameters.

The get_doc call returns a document by its ID. If no document ID is given it returns undef

    my $doc = $sc->get_doc({ id => 'doc_id', rev => '1-rev', dbname => 'database' });

where the dbname key is optional. Alternatively this works too:

    my $doc = $sc->get_doc('doc_id');

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

    my $rev = $sc->head_doc('doc_id');

This call returns a list of document IDs with their latest revision by default. Use "include_docs" to get all Documents attached as well.

    my @docs = $sc->all_docs({ include_docs => 'true' });

The get_design_docs call returns all design document names in an array. You can add "include_docs =" 'true'> to get whole design documents.

    my @docs = $sc->get_design_docs({ dbname => 'database' });

Again the "dbname" key is optional.

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 if you want to prevent creation of a new document in case the document ID is missing in your input hashref.

    my ($id, $rev) = $sc->put_doc({ doc => { .. }, 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. Returns the revision in SCALAR context, document ID and revision in ARRAY context.

    my $rev = $sc->del_doc({ id => 'doc_id', rev => 'r-evision', dbname => 'database' });

WARNING: as of Version 3.4 this method breaks old code!

The use of "update_doc()" was discouraged before this version and was merely a wrapper for put_doc, which became unnecessary. Please make sure you update your code if you were using this method before version 3.4.

"update_doc" refuses to push a document if the document ID is missing or the document does not exist. This will make sure that you can only update existing documents and not accidentally create a new one.

            $id = $sc->update_doc({ doc => { _id => '', _rev => '', ... } });
    ($id, $rev) = $sc->update_doc({ doc => { .. }, 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.

    my ($id, $rev) = $sc->copy_doc({ id => 'doc_id', dbname => 'database' });

call a show function on a document to transform it.

    my $content = $sc->show_doc({ show => 'design_doc/show_name' });

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.

    my $hashref = $sc->get_view({
        view => 'design_doc/view_name',
        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.

    my $hashref = $sc->get_post_view({
        view => 'design_doc/view_name',
        opts => [ $key1, $key2, $key3, ... ],
    });

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

    my @docs = @{ $sc->get_array_view({
        view => 'design_doc/view_name',
        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.

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

use the _list function on a view to transform its output. if your view contains a reduce function you have to add

    opts => { reduce => 'false' }

to your hash.

    my $content = $sc->list_view({
        list => 'list_name',
        view => 'design/view',
    #   opts => { reduce => 'false' },
    });

First draft of a changes feed implementation. Currently just returns the whole JSON structure received. This might change in the future. As usual the "dbname" key is optional if the database name is already set via the "db" attribute.

    my $changes = $sc->changes({dbname => 'database', limit => 100, since => 'now' });

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.

    my $result = $sc->purge({ dbname => 'database' });

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

    my $result = $sc->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 creates a new empty doc with the attachement otherwise. The 'file' and 'filename' parameters are mandatory.

    my ($id, $rev) = $sc->put_file({ file => 'content', filename => 'file.txt', id => 'doc_id' });

Get a file attachement from a CouchDB document.

    my $content = $sc->get_file({ id => 'doc_id', filename => 'file.txt' });

Delete a file attachement from a CouchDB document.

    my $content = $sc->del_file({ id => 'doc_id', rev => 'r-evision', filename => 'file.txt' });

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

    $sc->config({ host => 'HOST', port => 'PORT', db => 'DATABASE' });

Create a Database

    my $result = $sc->create_db('name');

Delete/Drop a Databse

    my $result = $sc->delete_db('name');

Get a list of all Databases

    my @db = $sc->all_dbs;

Please report any bugs or feature requests on GitHub's issue tracker <https://github.com/norbu09/Store-CouchDB/issues>. Pull requests welcome.

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

    perldoc Store::CouchDB

You can also look for information at:

  • GitHub repository

    <https://github.com/norbu09/Store-CouchDB>

  • MetaCPAN

    <https://metacpan.org/module/Store::CouchDB>

  • AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/Store::CouchDB>

  • CPAN Ratings

    <http://cpanratings.perl.org/d/Store::CouchDB>

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

Lenz Gschwendtner <norbu09@cpan.org>

This software is copyright (c) 2013 by Lenz Gschwendtner.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

2018-09-10 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.