view release on metacpan or  search on metacpan

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

=over 2

=item bulk => INTEGER

When there are not enough UUIDs in stock, in how large chuncks should we ask for
more.

=back

=item $obj-E<gt>B<requestUUIDs>($count, %options)

  [CouchDB API "GET /_uuids", since 2.0]

Returns UUIDs (Universally unique identifiers), when the call was
successful.  Better use L<freshUUIDs()|Couch::DB/"Ungrouped calls">.  It is faster to use Perl
modules to generate UUIDs.

=item $obj-E<gt>B<searchAnalyze>(\%config, %options)

  [CouchDB API "POST /_search_analyze", since 3.0, UNTESTED]

Check what the build-in Lucene tokenizer(s) will do with your text.  This uses
the Clouseau backend.

 -Option  --Default
  analyzer  <required>
  text      <required>

=over 2

=item analyzer => $kind

=item text => STRING

=back

=back

=head2 Processing

The methods in this section implement the CouchDB API.  You should
usually not need to use these yourself, as this libary abstracts them.

=over 4

=item $obj-E<gt>B<addClient>($client)

Add a L<Couch::DB::Client|Couch::DB::Client>-object to be used to contact the CouchDB
cluster.  Returned is the couch object, so these calls are stackable.

=item $obj-E<gt>B<call>($method, $path, %options)

Call some couchDB server, to get work done.  This is the base for any
interaction with the server.

Besides the explicitly listed parameters, this C<call> method is also responsible
for handling the generic parameters which influence the connection to the server
(like C<delay>, C<client>, and C<headers>) and hook into events (like C<on_final>
and C<on_error>).

B<Note:> you should probably not use this method yourself: all endpoint of
CouchDB are available via a nice, abstract wrapper.

 -Option--Default
  paging  +{}
  query   undef
  send    undef

=over 2

=item paging => \%config

When the endpoint support paging, then its needed configuration
data has been collected in here.  This enables the use of C<succeed>,
C<page>, C<skip>, and friends.  See examples in section L</Pagination>.

=item query => HASH

Query parameters for the request.

=item send => HASH

The content to be sent with POST and PUT methods.
in those cases, even when there is nothing to pass on, simply to be
explicit about that.

=back

=item $obj-E<gt>B<check>($condition, $change, $version, $what)

If the C<$condition> it C<true> (usually the existence of some parameter), then
check whether api limitiations apply.

Parameter C<$change> is either C<removed>, C<introduced>, or C<deprecated> (as
strings).  The C<version> is taken from the CouchDB API documentation.
The C<$what> describes the element, to be used in error or warning messages.

=item $obj-E<gt>B<client>($name)

Returns the client with the specific C<$name> (which defaults to the server's url).

=item $obj-E<gt>B<clients>(%options)

Returns a LIST with the defined clients; L<Couch::DB::Client|Couch::DB::Client>-objects.

 -Option--Default
  role    undef

=over 2

=item role => $role

When defined, only return clients which are able to fulfill the
specific C<$role>.

=back

=item $obj-E<gt>B<jsonText>($json, %options)

Convert the (complex) C<$json> structure into serialized JSON.  By default, it
is beautified.

 -Option --Default
  compact  false

=over 2

=item compact => BOOLEAN

Produce compact (no white-space) JSON.

=back

=item $obj-E<gt>B<listToPerl>($set, $type, @data|\@data)

Returns a LIST from all elements in the LIST C<@data> or the ARRAY, each
converted from JSON to pure Perl according to rule C<$type>.

=item $obj-E<gt>B<toJSON>(\%data, $type, @keys)

Convert the named fields in the C<%data> into a JSON compatible format.
Fields which do not exist are left alone.

At the moment, special treatment is implemented when C<$type> is
C<bool>, C<uri>, C<node> or C<int>.  When this method is called
with other types, the data is untouched.

=item $obj-E<gt>B<toPerl>(\%data, $type, @keys)

Convert all fields with C<@keys> in the C<%data> HASH into object
of C<$type>.  Fields which do not exist are ignored.

As default JSON to Perl translations are currently defined for C<$type>
being C<abs_uri>, C<epoch>, C<isotime>, C<mailtime>, C<version>,
and C<node>.  Other values for C<$type> will not trigger any action.

=item $obj-E<gt>B<toQuery>(\%data, $type, @keys)

Convert the named fields in the C<%data> HASH into a Query compatible
format.  Fields which do not exist are left alone.

At the moment, special treatment is implemented when C<$type> is
C<bool> or C<json>.

=back

=head1 DETAILS

=head2 Early adopters

B<Be warned> that this module is really new.  The 127 different endpoints
that the CouchDB 3.3.3 API defines, are grouped and combined.  The result
is often not tested, and certainly not combat ready.  Please, report
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.

This library also converts parameters from Perl space into JSON space.
POST and PUT parameters travel in JSON documents.  In JSON, a boolean is
C<true> and C<false> (without quotes).  In Perl, these are C<undef> and
C<1> (and many alternatives).  For anything besides your own documents,
C<Couch::DB> will totally hide these differences for you!

=head3 Generic parameters

Each method which is labeled C<< [CouchDB API] >> also accepts a few options
which are controlling the calling progress.  They are handled by the L<call()|Couch::DB/"Processing">
method which implements the API calls.

These parameters are available for every API call, hence no-where
documented explicitly.  These options are either about the connection
between client and server, for result paging, or processing event hooks.

=head4 Connection parameters

At the moment, the following generic C<%options> are supported everywhere:

=over 4

=item * C<delay> =E<gt> BOOLEAN, default C<false>

Do not perform and wait for the actual call, but prepare it to be used in parallel
querying.  TO BE IMPLEMENTED/DOCUMENTED.

=item * C<client> =E<gt> C<$client>-object or -name

Use only the specified client (=server) to perform the call.

=item * C<clients> =E<gt> ARRAY-of-clients or a role

Use any of the specified clients to perform the call.  When not an ARRAY, the
parameter is a C<role>: select all clients which can perform that role (the
logged-in user of that client is allowed to perform that task).

=item * C<headers> =E<gt> HASH

Add headers to the request.  When applicable (for instance, the C<Accept>-header)
this will overrule the internally calculated defaults.

=back