view release on metacpan or  search on metacpan

lib/AnyEvent/CouchDB/Database.pm  view on Meta::CPAN

__END__

=head1 NAME

AnyEvent::CouchDB::Database - an object representing a CouchDB database

=head1 SYNOPSIS

  use AnyEvent::CouchDB;
  $db = couchdb('bavl');
  my $map = 'function(doc){
    if(doc.type == "Phrase"){ emit(null, doc) }
  }';
  my $phrases = $db->query($map)->recv;
  my $recordings = $db->view('recordings/all')->recv;

=head1 DESCRIPTION

Objects of this class represent a single CouchDB database.  This object is used
create and drop databases as well as operate on the documents within the database.

=head1 API

=head2 General

=head3 $db = AnyEvent::CouchDB::Database->new($name, $uri)

This method takes a name and a URI, and constructs an object representing a
CouchDB database.  The name should be conservative in the characters it uses,
because it needs to be both URI friendly and portable across filesystems.
Also, the URI that you pass in should contain a trailing slash.

=head3 $db->name

This method returns the name of the database.

=head3 $db->uri

This method returns the base URI of the database.

=head3 $db->json_encoder([ $json_encoder ])

This method is a mutator for setting a custom JSON encoder.  You should
pass in an object that responds to C<encode> and C<decode>.  Instances of
L<JSON> and L<JSON::XS> are good candidates.

=head2 Options

All the methods that accept an optional hashref of options can set an "headers"
key, wich will be added to all the requests. So you can add basic
authentication to your requests if needed:

  my $couchdb = couch("http://127.0.0.1:5984/");
  my $db      = $couchdb->db("mydb");
  my $auth    = encode_base64('user:s3kr3t', '');

  my $res = $db->create({headers => {'Authorization' => 'Basic '.$aut}})->recv;

B<UPDATE>:  You can now make authenticated requests by placing the username and
password in the URI.

  my $db = couchdb('http://user:s3kr3t@127.0.0.1:5984/mydb');

=head2 Database Level Operations

=head3 $cv = $db->create([ \%options ])

This method is used to create a CouchDB database.  It returns an L<AnyEvent>
condvar.

=head3 $cv = $db->drop([ \%options ])

This method is used to drop a CouchDB database, and it returns a condvar.

=head3 $cv = $db->info([ \%options ])

This method is used to request a hashref of info about the current CouchDB
database, and it returns a condvar.

=head3 $cv = $db->compact([ \%options ])

This method is used to request that the current CouchDB database
be compacted, and it returns a condvar.

=head2 Document Level Operations

=head3 $cv = $db->open_doc($id, [ \%options ])

This method is used to request a single CouchDB document by its C<id>, and
it returns a condvar.

=head3 $cv = $db->open_docs($ids, [ \%options ])

This method is used to request multiple CouchDB documents by their C<ids>, and
it returns a condvar.

=head3 $cv = $db->save_doc($doc, [ \%options ])

This method can be used to either create a new CouchDB document or update an
existing CouchDB document.  It returns a condvar.

Note that upon success, C<$doc> will have its C<_id> and C<_rev> keys
updated.  This allows you to save C<$doc> repeatedly using the same hashref.

=head3 $cv = $db->remove_doc($doc, [ \%options ])

This method is used to remove a document from the database, and it returns a
condvar.

=head3 $cv = $db->attach($doc, $attachment, \%options)

This method adds an attachment to a document, and it returns a condvar.  Note
that the C<%options> are NOT optional for this method.  You must provide a
C<src> for the data which should be a path that can be understood by
L<IO::All>.  You must also provide a MIME content C<type> for this data.  If
none is provided, it'll default to C<text/plain>.

B<Example>:

  $db->attach($doc, "issue.net", {