The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Couch-DB-0.005
River stage zero No dependents
/ Couch::DB::Client

NAME

Couch::DB::Client - connect to a CouchDB node

SYNOPSIS

  my $client = Couch::DB::Client->new(couch => $couchdb, ...);
  $couch->addClient($client);

  my $client = $couch->createClient(...);  # same in one step

  # Even simpler
  my $couch  = Couch::DB::Mojolicious->new(server => ...);
  my $client = $couchdb->client('local');   # default client

DESCRIPTION

Connect to a CouchDB-server which runs a CouchDB-node to host databases. That node may be part of a cluster, which can be managed via Couch::DB::Cluster

METHODS

Constructors

Couch::DB::Client->new(%options)

Create the client. Whether it works will show when the first call is made. You could try serverStatus() on application startup.

 -Option    --Default
  auth        'BASIC'
  couch       <required>
  headers     <a few>
  name        server
  password    undef
  server      <required>
  user_agent  <required>
  username    undef
auth => 'BASIC'|'COOKIE'
couch => Couch::DB-object
headers => HASH

Some headers are set by default, for instance the 'Accept' header. You can overrule them. The defaults may change.

With this option you can also provide proxy authentication headers, of the form X-Auth-CouchDB-*.

name => STRING

A good symbolic name for the client may make it more readible. Defaults to the location of the server.

password => STRING
server => URL-object

Pass a URL-object which fits the framework your choose.

user_agent => UserAgent-Object

Pass a UserAgent-object which fits the framework your choose.

username => STRING

When you specify a username/password here, then Basic authentication will be used. Otherwise, call login() to use Cookies.

Accessors

$obj->couch()

Returns the active Couch::DB object.

$obj->headers()

Returns a HASH with the default set of headers to be used when contacting this client.

$obj->name()
$obj->server()

Returns the URL of the server which is addressed by this client.

Which type of object is used, depends on the event framework. For instance a Mojo::URL when using Couch::DB::Mojolicious.

$obj->userAgent()

Returns the user-agent object which connects to the servers.

Which type of object is used, depends on the event framework. for instance a Mojo::UserAgent when using Couch::DB::Mojolicious.

Session

$obj->hasRole($role)
 [UNTESTED]

Return 'true' if (this user logged-in to the server with) this client can perform a certain role.

It is often preferred to try a certain action, and then check whether it results in a permission error.

$obj->login(%options)
 [CouchDB API "POST /_session", UNTESTED]

Get a Cookie: Cookie authentication.

TODO: implement refreshing of the session.

 -Option  --Default
  next      undef
  password  <required>
  username  <required>
next => URL

When the login was successful, the UserAgent will get redirected to the indicated location.

password => STRING
username => STRING
$obj->logout(%options)
 [CouchDB API "DELETE /_session", UNTESTED]

Terminate the session.

$obj->roles()
 [UNTESTED]

Returns a LIST of all roles this client can perform.

$obj->session(%options)
 [CouchDB API "GET /_session", UNTESTED]

Returns information about the current session, like information about the user who is logged-in. Part of the reply is the "userCtx" (user context) which displays the roles of this user, and its name.

 -Option--Default
  basic   undef
basic => BOOLEAN

Server information

All CouchDB API calls documented below, support %options like _delay and on_error. See "Using the CouchDB API" in Couch::DB.

These are only for web-interfaces:

 [CouchDB API "GET /favicon.ico", UNSUPPORTED]
 [CouchDB API "GET /_utils", UNSUPPORTED]
 [CouchDB API "GET /_utils/", UNSUPPORTED]
$obj->activeTasks(%options)
 [CouchDB API "GET /_active_tasks"]

Query details about the (maintenance) tasks which are currently running in the connected server. Returns a Couch::DB::Result object.

$obj->clusterNodes(%options)
 [CouchDB API "GET /_membership", since 2.0, UNTESTED]

List all known nodes, and those currently used for the cluster.

$obj->databaseInfo(%options)
 [CouchDB API "GET /_dbs_info", since 3.2]
 [CouchDB API "POST /_dbs_info", since 2.2]

Returns detailed information about the selected database keys, on the connected CouchDB instance. Both the GET and POST alternatives produce the same structures.

When both keys and search are missing, then all databases are reported.

 -Option--Default
  names   undef
  search  undef
names => ARRAY

When you provide explicit database keys, then only those are displayed. The number of keys is limited by the max_db_number_for_dbs_info_req configuration parameter, which defaults to 100.

search => \%search

Use the filter options described by databaseNames().

$obj->databaseNames(%options)
 [CouchDB API "GET /_all_dbs"]

Returns the selected database names as present on the connected CouchDB instance.

 -Option--Default
  search  undef
search => \%search

You can specify a name (=key) filter: specify a subset of names to be returned.

$obj->dbUpdates(\%feed, %options)
 [CouchDB API "GET /_db_updates", since 1.4, UNTESTED]

Get a feed of database changes, mainly for debugging purposes.

$obj->node()

Returns the Couch::DB::Node which is run by the connected CouchDB instance. This fact is cached.

$obj->nodeName($name, %options)
 [CouchDB API "GET /_node/{node-name}", UNTESTED]

The only useful application is with the abstract name _local, which will return you the name of the node represented by the CouchDB instance.

$obj->replicate(\%rules, %options)
 [CouchDB API "POST /_replicate", UNTESTED]

Configure replication: configure and stop.

All %options are posted as parameters.

$obj->replicationDoc($doc|$docid, %options)
 [CouchDB API "GET /_scheduler/docs/{replicator_db}/{docid}", UNTESTED]

Retrieve information about a particular replication document. Supports pagination.

 -Option--Default
  dbname  _replicator
dbname => NAME

Pass a dbname for the database which contains the replication information.

$obj->replicationDocs(%options)
 [CouchDB API "GET /_scheduler/docs", UNTESTED]
 [CouchDB API "GET /_scheduler/docs/{replicator_db}", UNTESTED]

Retrieve information about replication documents. Supports pagination.

 -Option--Default
  dbname  _replicator
dbname => NAME

Pass a dbname for the database which contains the replication information.

$obj->replicationJobs(%options)
 [CouchDB API "GET /_scheduler/jobs", UNTESTED]

Returns information about current replication jobs (which preform tasks), on this CouchDB server instance. The results are ordered by replication ID.

Supports pagination.

$obj->serverInfo(%options)
 [CouchDB API "GET /"]

Query details about the server this client is connected to. Returns a Couch::DB::Result object.

 -Option--Default
  cached  'YES'
cached => 'YES'|'NEVER'|'RETRY'|'PING'

Reuse the results of the previous ping to the server? This old request might have resulted in a connection error, so the cached data may continue to show an error while the problem has disappeared. With RETRY, the cached data will be used when the previous ping was successful. When PING, then the call will be made, but the old successfully retreived information will not be lost.

$obj->serverIsUp()
 [UNTESTED]

Returns a true value when the server status is "ok".

$obj->serverStatus(%options)
 [CouchDB API "GET /_up", since 2.0, UNTESTED]

Probably you want to use serverIsUp(), because this reply contains little information.

$obj->version()

Returns the version of the server software, as version object.

SEE ALSO

This module is part of Couch-DB distribution version 0.005, built on June 23, 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/