view release on metacpan or  search on metacpan

lib/Couch/DB.pod  view on Meta::CPAN

the result of calls which are currently flagged "UNTESTED".

B<Please help> me fix issues by reporting them.  Bugs will be solved within
a day.  Please, contribute ideas to make the use of the module lighter.
Together, we can make the quality grow fast.

=head2 Integration with your framework

You need to instantiate an extensions of this class.  At the moment,
you can pick from:

=over 4

=item * L<Couch::DB::Mojolicious|Couch::DB::Mojolicious>

Implements the client using the Mojolicious framework, using Mojo::URL,
Mojo::UserAgent, Mojo::IOLoop, and many other.

=back

Other extensions are hopefully added in the future.  Preferrably as part
of this release so it gets maintained together.  The extensions are not
too difficult to create and certainly quite small.

=head2 Thick interface

The CouchDB client interface is based on HTTP.  It is really easy to
construct a JSON, and then use a UserAgent to send it to the CouchDB
server.  All other CPAN modules which support CouchDB stick on this
level of support; except C<Couch::DB>.

When your library is very low-level, your program needs to put effort to
create an abstraction around the interface it itself.  When the library
offers that abstraction already, you need to write much less code!

The Perl programming language works with functions, methods, and
objects, so why would your libary require you to play with URLs?
So, C<Couch::DB> has the following extra features:

=over 4

=item *

Calls have a functional name, and are grouped into classes: the
endpoint URL processing is totally abstracted away;

=item *

Define multiple clients at the same time, for automatic fail-over,
read, write, and permission separation, or parallellism;

=item *

Resolving differences between CouchDB-server versions.  You may
even run different CouchDB versions on your nodes;

=item *

JSON-types do not match Perl's type concept: this module will
convert boolean and integer parameters (and more) from Perl to
JSON and back transparently;

=item *

Offer error handling and event processing on each call;

=item *

Event framework independent (currently only a Mojolicious connector).

=back

=head2 Using the CouchDB API

All methods which are marked with C<< [CouchDB API] >> are, as the name
says: client calls to some CouchDB server.  Often, this connects to a node
on your local server, but you can also connect to other servers and even
multiple servers.

All these API methods return a L<Couch::DB::Result|Couch::DB::Result> object, which can tell
you how the call worked, and the results.  The resulting object is overloaded
boolean to produce C<false> in case of an error.  So typically:

  my $couch  = Couch::DB::Mojolicious->new(version => '3.3.3');
  my $result = $couch->requestUUIDs(100);
  $result or die;

  my $uuids  = $result->values->{uuids};

This CouchDB library hides the fact that endpoint C</_uuids> has been called.
It also hides the client (UserAgent) which was used to collect the data.

You could also write

  my $uuids  = $couch->requestUUIDs(100)->values->{uuids};

because "values()" will terminate when the database call did not result
in a successful answer.  Some convenience methods are provided as well,
which makes the last alternative:

  my @uuids = $couch->freshUUIDs(100);

=head3 Where can I find what?

The CouchDB API lists all endpoints as URLs.  This library, however,
creates an Object Oriented interface around these calls: you do not
see the internals in the resulting code.  Knowing the CouchDB API,
it is usually immediately clear where to find a certain end-point:
C<< /{db} >> will be in L<Couch::DB::Database|Couch::DB::Database>.  A major exception is
anything what has to do with replication and sharding: this is bundled
in L<Couch::DB::Cluster|Couch::DB::Cluster>.

Have a look at L<https://perl.overmeer.net/couch-db/reference.html>.
Keep that page open in your browser while developing.

=head3 Type conversions

With the L<Couch::DB::Result::values()|Couch::DB::Result/"When the document is collected"> method, conversions between JSON
syntax and pure Perl are done.  This also hides database interface changes
for you, based on your L<new(api)|Couch::DB/"Constructors"> setting.  Avoid L<Couch::DB::Result::answer()|Couch::DB::Result/"When the document is collected">,
which gives the uninterpreted, unabstracted results.