NAME

CouchDB::Client::DB - CouchDB::Client database

SYNOPSIS

        use CouchDB::Client;
        my $c = CouchDB::Client->new(uri => 'https://dbserver:5984/');
        my $db = $c->newDB('my-stuff')->create;
        $db->dbInfo;
        my $doc = $db->newDoc('dahut.svg', undef, { foo => 'bar' })->create;
        my $dd = $db->newDesignDoc('dahut.svg', undef, $myViews)->create;
        #...
        $db->delete;

DESCRIPTION

This module represents databases in the CouchDB database.

We don't currently handle the various options available on listing all documents.

METHODS

new

Constructor. Takes a hash or hashref of options, both of which are required: name being the name of the DB (do not escape it, that is done internally, however the name isn't validated, you can use validName for that) and client being a reference to the parent Couch::Client. It is not expected that you would use this constructor directly, but rather that would would go through Couch::Client->newDB.

validName $NAME

Returns true if the name is a valid CouchDB database name, false otherwise.

dbInfo

Returns metadata that CouchDB maintains about its databases as a Perl structure. It will throw an exception if it can't connect. Typically it will look like:

        {
                db_name         => "dj",
                doc_count       => 5,
                doc_del_count   => 0,
                update_seq      => 13,
                compact_running => 0,
                disk_size       => 16845,
        }

create

Performs the actual creation of a database. Returns the object itself upon success. Throws an exception if it already exists, or for connection problems.

delete

Deletes the database. Returns true on success. Throws an exception if the DB can't be found, or for connection problems.

replicate %ARGS

Sets up replication between two databases. Setting target to a database url (either local or remote) replicates this database into one specified by the url. Conversely, setting source to a database url replicates that database into the current one. In CouchDB terminology, target and source, respectively, set up "push" and "pull" replication.

Either target or source is required; both can't be used at the same time.

By default, replication is a one time event. New modifications to the origin database do not automatically appear in the replicated database. Setting continuous to a true value will cause new changes in the origin database to be reflected in the replicated one.

Note: Support for the create_target flag (which was added after version 0.10) is included, but untested.

newDoc $ID?, $REV?, $DATA?, $ATTACHMENTS?

Returns a new CouchDB::Client::Doc object, optionally with the given ID, revision, data, and attachments. Note that this does not create the actual document, simply the object. For constraints on these fields please look at <<CouchDB::Client::Doc-new>>>

listDocIdRevs %ARGS?

Returns an arrayref containing the ID and revision of all documents in this DB as hashrefs with id and rev keys. Throws an exception if there's a problem. Takes an optional hash of arguments matching those understood by CouchDB queries.

listDocs %ARGS?

The same as above, but returns an arrayref of CouchDB::Client::Doc objects. Takes an optional hash of arguments matching those understood by CouchDB queries.

docExists $ID, $REV?

Takes an ID and an optional revision and returns true if there is a document with that ID in this DB, false otherwise. If the revision is provided, note that this will match only if there is a document with the given ID and its latest revision is the same as the given one.

newDesignDoc $ID?, $REV?, $DATA?

Same as above, but instantiates design documents.

listDesignDocIdRevs %ARGS?

Same as above, but only matches design documents.

listDesignDocs %ARGS?

Same as above, but only matches design documents.

designDocExists $ID, $REV?

Same as above, but only matches design documents.

tempView $VIEW

Given a view (defined as a hash with the fields that CouchDB expects from the corresponding JSON), will run it and return the CouchDB resultset. Throws an exception if there is a connection error.

bulkStore \@DOCS

Takes an arrayref of Doc objects and stores them on the server (creating or updating them depending on whether they exist or not). Returns the data structure that CouchDB returns on success (which is of limited interest as this client already updates all documents so that their ID and revisions are correct after this operation), and throws an exception upon failure.

bulkDelete \@DOCS

Same as above but performs mass deletion of documents. Note that using bulkStore you could also obtain the same effect by setting a _deleted field to true on your objects but that is not recommended as fields that begin with an underscore are reserved by CouchDB.

uriName

Returns the name of the database escaped.

fixViewArgs %ARGS

Takes a hash of view parameters expressed in a Perlish fashion (e.g. 1 for true or an arrayref for multi-valued keys) and returns a hash with the same options turned into what CouchDB understands.

argsToQuery %ARGS

Takes a hash of view parameters, runs them through fixViewArgs, and returns a query string (complete with leading '?') to pass on to CouchDB.

AUTHOR

Robin Berjon, <robin @t berjon d.t com> Maverick Edwards, <maverick @t smurfbane d.t org> (current maintainer)

BUGS

Please report any bugs or feature requests to bug-couchdb-client at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CouchDB-Client.

COPYRIGHT & LICENSE

Copyright 2008 Robin Berjon, all rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.