NAME
Couch::DB - CouchDB database client
INHERITANCE
Couch::DB is extended by
Couch::DB::Mojolicious
SYNOPSIS
use Couch::DB::Mojolicious ();
my $couch = Couch::DB::Mojolicious->new(api => '3.3.3');
my $db = $couch->db('my-db'); # Couch::DB::Database object
my $cluster = $couch->cluster; # Couch::DB::Cluster object
my $client = $couch->createClient(...); # Couch::DB::Client
DESCRIPTION
When this module was written, there were already a large number of CouchDB implementations on CPAN. Still, there was a need for one more. This implementation provides a thick interface: a far higher level of abstraction than the other modules. This should make your work much, much easier.
Also, open https://perl.overmeer.net/couch-db/reference.html in a browser window, as useful cross-reference: parameters for CouchDB are not documented in this Perl documentation!
Please read the "DETAILS" section, further down, at least once before you start!
Early adopters
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 battle ready.
Please help me fix issues by reporting them. Bugs will be solved within a day. Please, contribute useful ideas to make the use of the module lighter. Together, we can make the quality grow fast.
Integration with your framework
You need to instantiate an extensions of this class. At the moment, you can pick from:
-
Implements the client using the Mojolicious framework, using Mojo::URL, Mojo::UserAgent, Mojo::IOLoop, and many other.
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.
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. Knowing the CouchDB API, it is usually immediately clear where to find a certain end-point: /{db}
will be in Couch::DB::Database. A major exception is anything what has to do with replication and sharding: this is bundled in Couch::DB::Cluster.
Have a look at https://perl.overmeer.net/couch-db/reference.html. Keep that page open in your browser while developing.
METHODS
Constructors
- Couch::DB->new(%options)
-
Create a relation with a CouchDB server(cluster). You should use totally separated Couch::DB-objects for totally separate database clusters. Note: you can only instantiate extensions of this class.
When you do not specify a
server
-url, but have an environment variablePERL_COUCH_DB_SERVER
, then server url, username, and password are derived from it.-Option --Default api <required> auth 'BASIC' password undef server "http://127.0.0.1:5984" to_json +{ } to_perl +{ } to_query +{ } username undef
- api => $version
-
You have to specify the version of the server you expect to answer your queries. Couch::DB tries to hide differences between your expectations and the reality.
The $version can be a string or a version object (see "man version").
- auth => 'BASIC'|'COOKIE'
-
Authentication method to be used by default for each client.
- password => STRING
- server => URL
-
The default server to connect to, by URL. See
etc/local.ini[chttpd]
This server will be named 'local'.You can add more servers using addClient(). In such case, you probably do not want this default client to be created as well. To achieve this, explicitly set
server => undef
here. - to_json => HASH
-
A table with converter name and CODE, to override/add the default PERL to JSON object conversions for sending structures. See toJSON().
- to_perl => HASH
-
A table with converter name and CODE, to override/add the default JSON to PERL object conversions for Couch::DB::Result::values(). See toPerl() and listToPerl().
- to_query => HASH
-
A table with converter name and CODE, to override/add the default PERL to URL QUERY conversions. Defaults to the json converters. See toQuery().
- username => STRING
-
When a
username
is given, it will be used together withauth
andpassword
to login to any created client.
Accessors
- $obj->api()
-
Returns the interface version you expect the server runs, as a version object. Differences between reality and expectations are mostly automatically resolved.
Interface starting points
- $obj->cluster()
-
Returns a Couch::DB::Cluster-object, which organizes calls to manipulate replication, sharding, and related jobs. This will always return the same object.
- $obj->createClient(%options)
-
Create a client object which handles a server. All options are passed to Couch::DB::Client. The
couch
parameter is added for you. The client will also be added via addClient(), and is returned.It may be useful to create to clients to the same server: one with admin rights, and one without. Or clients to different nodes, to create fail-over.
- $obj->db($name, %options)
-
Define a dabase. The database may not exist yet. Calling this method does nothing with the CouchDB server.
my $db = $couch->db('authors'); $db->ping or $db->create(...);
- $obj->node($name)
-
Returns a Couch::DB::Node-object with the $name. If the object does not exist yet, it gets created, otherwise reused.
- $obj->searchAnalyse(%options)
-
[CouchDB API "POST /_search_analyze", since 3.0, UNTESTED]
Check what the build-in Lucene tokenizer(s) will do with your text.
-Option --Default analyzer <required> text <required>
Server connections
- $obj->addClient($client)
-
Add a Couch::DB::Client-object to be used to contact the CouchDB cluster. Returned is the couch object, so these calls are stackable.
- $obj->call(\%options|($method, $path, %options))
-
Call some couchDB server, to get work done. This is the base for any interaction with the server.
-Option --Default bookmark undef client undef clients undef delay false method <required> paginate false path <required> query undef send undef to_values undef
- bookmark => STRING
-
When you magically come up with the same query, and a related bookmark (save
$result->next
in the session?), then you get a next page. - client => Couch::DB::Client
- clients => ARRAY|$role
-
Explicitly use only the specified clients (Couch::DB::Client-objects) for the query. When none are given, then all are used (in order of precedence). When a $role (string) is provided, it is used to select a subset of the defined clients.
- delay => BOOLEAN
-
[PARTIAL]
Do not execute the server call yet, but prepare it only in a way that it can be combined with other clients in parallel. See Couch::DB::Result chapter "DETAILS" about delayed requests.
- method => 'GET'|'POST'|...
-
HTTP transport method. Positional parameter when a LIST is passed.
- paginate => BOOLEAN
-
This call supports pagination via bookmarks. This enables the use of Couch::DB::Result::nextPage().
- path => $url
-
HTTP endpoint. Positional parameter when a LIST is passed.
- query => HASH
-
Query parameters for the request.
- 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.
- to_values => CODE
-
A function (sub) which transforms the data of the CouchDB answer into useful Perl values and objects. See Couch::DB::toPerl().
- $obj->client($name)
-
Returns the client with the specific $name (which defaults to the server's url).
- $obj->clients(%options)
-
Returns a LIST with the defined clients; Couch::DB::Client-objects.
-Option--Default role undef
Conversions
- $obj->check($condition, $change, $version, $what)
-
If the $condition it true (usually the existence of some parameter), then check whether api limitiations apply.
Parameter $change is either
removed
,introduced
, ordeprecated
(as strings). Theversion
is taken from the CouchDB API documentation. The $what describes the element, to be used in error or warning messages. - $obj->freshUUIDs($count, %options)
-
[UNTESTED]
Returns a $count number of UUIDs in a LIST. This uses requestUUIDs() to get a bunch at the same time, for efficiency. You may get fewer than you want, but only when the server is not sending them.
-Option--Default bulk 50
- $obj->jsonText($json, %options)
-
Convert the (complex) $json structure into serialized JSON. By default, it is beautified.
-Option --Default compact false
- $obj->listToPerl($set, $type, @data|\@data)
-
Returns a LIST from all elements in the LIST @data or the ARRAY, each converted from JSON to pure Perl according to rule $type.
- $obj->requestUUIDs($count, %options)
-
[CouchDB API "GET /_uuids", since 2.0, UNTESTED]
Returns UUIDs (Universally unique identifiers), when the call was successful. Better use freshUUIDs(). It is faster to use Perl modules to generate UUIDs.
- $obj->toJSON(\%data, $type, @keys)
-
Convert the named fields in the %data into a JSON compatible format. Fields which do not exist are left alone.
- $obj->toPerl(\%data, $type, @keys)
-
Convert all fields with @keys in the %data HASH into object of $type. Fields which do not exist are ignored.
As default JSON to Perl translations are currently defined:
abs_uri
,epoch
,isotime
,mailtime
,version
, andnode
. - $obj->toQuery(\%data, $type, @keys)
-
Convert the named fields in the %data HASH into a Query compatible format. Fields which do not exist are left alone.
DETAILS
Thick interface
The CouchDB client interface is based on HTTP. It is really easy to create 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; not Couch::DB
.
When your library is very low-level, your program needs to put effort to create an abstraction around it itself. In case the library offers that abstraction, 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, Couch::DB
has the following extra features:
Calls have a functional name, and are grouped into objects: the endpoint URL processing is totally abstracted away;
Define multiple clients at the same time, for automatic fail-over, read, write, and permission separation, or parallellism;
Resolving differences between CouchDB-server instances. You may even run different CouchDB versions on your nodes;
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;
Offer error handling and event processing on each call;
Event framework independent (currently only a Mojolicious connector).
Using the CouchDB API
All methods which are marked with [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 Couch::DB::Result object, which can tell you how the call worked, and the results. The resulting object is overloaded boolean to produce 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 /_uuids
has been called. It also hides the client (UserAgent) which was used to collect the data.
Type conversions
With the Couch::DB::Result::values()
method, conversions between JSON syntax and pure Perl are done.
More importantly: this library also converts parameters from Perl space into JSON space. POST and PUT parameters travel in JSON documents. In JSON, a boolean is true
and false
(without quotes). In Perl, these are undef
and 1
(and many alternatives). For anything besides your own documents, Couch::DB
will totally hide these differences for you!
Generic parameters
Each method which is labeled [CouchDB API]
also accepts a few options which are controlling the calling progress. They are available everywhere, hence no-where documented explicitly. Those options start with an underscore (_
) or with on_
(events).
At the moment, the following %options are supported:
_delay
=> BOOLEAN, defaultfalse
Do not perform and wait for the actual call, but prepare it to be used in parallel querying. TO BE IMPLEMENTED/DOCUMENTED.
_client
=> $client-object or -nameUse only the specified client (=server) to perform the call.
_clients
=> ARRAY-of-clients or a roleUse any of the specified clients to perform the call. When not an ARRAY, the parameter is a
role
: select all clients which can perform that role (the logged-in user of that client is allowed to perform that task)._headers
=> HASHAdd headers to the request. When applicable (for instance, the
Accept
-header) this will overrule the internally calculated defaults.
Besides, at the moment we support the following events:
on_error
=> CODE or ARRAY-of-CODEA CODE (sub) which is called when the interaction with the server has been completed without success. The CODE gets the result object as only parameter.
on_final
=> CODE or ARRAY-of-CODEA CODE (sub) which is called when the interaction with the server has been completed. This may happen much later, when combined with
_delay
. The CODE gets the result object as only parameter.
SEE ALSO
This module is part of Couch-DB distribution version 0.002, built on May 31, 2024. Website: http://perl.overmeer.net/CPAN/
LICENSE
Copyrights 2024 by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/