NAME

Couch::DB::Database - One database connection

SYNOPSIS

my $db   = Couch::DB->db('my-db');

# (search) documents in the database
my @docs = $db->allDocs->docs;

DESCRIPTION

One node (server) contains multiple databases. Databases do not contain "collections", like MongoDB: each document is a direct child of a database. Per database, you get multiple files to store that data, for views, replication, and so on. Per database, you need to set permissions.

Clustering, sharing, and replication activities on a database are provided by the Couch::DB::Cluster package.

METHODS

Constructors

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

Do not call this method yourself, but use Couch::DB::db() to instantiate this object.

-Option--Default
 batch   false
 couch   <required>
 name    <required>

batch => BOOLEAN: When set, all write actions (which support this) to this database will not wait for the actual update of the database. This gives a much higher performance, but not all errors may be reported.
couch => Couch::DB-object
name => STRING: The name of a database must match ^[a-z][a-z0-9_$()+/-]*$.

Accessors

$obj->batch()
$obj->couch()
$obj->name()

Database information

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

$obj->changes(%options)

[CouchDB API "GET /{db}/_changes", TODO]
[CouchDB API "POST /{db}/_changes", TODO]

Feed of changes made on this database.

$obj->compact(%options)

[CouchDB API "POST /{db}/_compact"]
[CouchDB API "POST /{db}/_compact/{ddoc}", UNTESTED]

Instruct the database files to be compacted now. By default, the data gets compacted on unexpected moments.

-Option--Default
 design  undef

design => $design|$ddocid: Compact all indexes related to this design document, instead.

$obj->create(%options)

[CouchDB API "PUT /{db}"]

Create a new database. The result object will have code HTTP_CREATED when the database is successfully created. When the database already exists, it returns HTTP_PRECONDITION_FAILED and an error in the body.

Options: partitioned (bool), q (number of shards, default 8), and n (number of replicas, defaults to 3).

$obj->details(%options)

[CouchDB API "GET /{db}"]
[CouchDB API "GET /{db}/_partition/{partition}", UNTESTED]

Collect information from the database, for instance about its clustering.

-Option   --Default
 partition  undef

partition => $partition

$obj->ensureFullCommit(%options)

[CouchDB API "POST /{db}/_ensure_full_commit", deprecated 3.0.0]

Support for old replicators.

$obj->exists()

Returns a boolean, whether the database exist on the server. This will call ping() and wait for an anwser.

$obj->ping(%options)

[CouchDB API "HEAD /{db}"]

Check whether the database exists. You may get some useful response headers, but nothing more: the response body is empty.

$obj->purgeDocs(\%plan, %options)

[CouchDB API "POST /{db}/_purge", UNTESTED]

Remove selected document revisions from the database.

A deleted document is only marked as being deleted, but exists until purge. There must be sufficient time between deletion and purging, to give replication a chance to distribute the fact of deletion.

$obj->purgeUnusedViews(%options)

[CouchDB API "POST /{db}/_view_cleanup", UNTESTED]

Removes view files that are not used by any design document.

$obj->purgedRecordsLimit(%options)

[CouchDB API "GET /{db}/_purged_infos_limit", UNTESTED]

Returns the soft maximum number of records kept about deleting records.

$obj->purgedRecordsLimitSet($limit, %options)

[CouchDB API "PUT /{db}/_purged_infos_limit", UNTESTED]

Set a new soft limit. The default is 1000.

$obj->remove(%options)

[CouchDB API "DELETE /{db}"]

Remove the database.

example: be sure a database does not exist

Any call returns a success, which you should test; there are many reasons why they may fail. So, for any call, you should write like this:

my $r = $couch->db('test')->remove;
$r or error "Cannot remove database 'test'; $r";

However, in this case you may not want to cast an error at reply code 404 (not found). Away means away. So, this works:

$r && $r->code != 404 or error $r;

use HTTP::Status  qw(HTTP_NOT_FOUND);
$r && $r->code != HTTP_NOT_FOUND or error $r;

$obj->revisionLimit(%options)

[CouchDB API "GET /{db}/_revs_limit", UNTESTED]

Returns the limit of historical revisions to store for a single document in the database.

$obj->revisionLimitSet($limit, %options)

[CouchDB API "PUT /{db}/_revs_limit", UNTESTED]

Sets the limit of historical revisions to store for a single document in the database. The default is 1000.

$obj->revisionsDiff(\%plan, %options)

[CouchDB API "POST /{db}/_revs_diff", UNTESTED]

With given a list of document revisions, returns the document revisions that do not exist in the database.

$obj->revisionsMissing(\%plan, %options)

[CouchDB API "POST /{db}/_missing_revs", UNTESTED]

With given a list of document revisions, returns the document revisions that do not exist in the database.

$obj->userRoles(%options)

[CouchDB API "GET /{db}/_security"]

Returns the users who have access to the database, including their roles (permissions).

Usually, it is better to simply attempt to take an action, and handle the errors: having a role does not mean that the action will be error-less anyway.

$obj->userRolesChange(%options)

[CouchDB API "PUT /{db}/_security", UNTESTED]

Returns the users who have access to the database, including their roles (permissions).

-Option --Default
 admin    [ ]
 members  [ ]

admin => ARRAY
members => ARRAY

Indexes

Three indexes exist:

json (Mango)
text (Lucene via Cousteau, phased out)
nouveau (Lucene via Nouveau, since 3.4.1)

The details about each index are stored in design documents. You may have more than one index per design document, but any change to such document will force a rebuild of all other indices in the same file.

$obj->design( [$ddocid|$ddoc|undef] )

Returns the Couch::DB::Design object which manages a design document. The document will not be read until an explicit call to get(). The $ddocid may start with _design/ which will be ignored.

$obj->designs( [\%search|\@%search, %options] )

[CouchDB API "GET /{db}/_design_docs", UNTESTED]
[CouchDB API "POST /{db}/_design_docs", UNTESTED]
[CouchDB API "POST /{db}/_design_docs/queries", UNTESTED]

Pass one or more %search queries to be run. The default returns all designs. The search query looks very much like a generic view search, but a few parameters are added and missing.

If there are searches, then GET is used, otherwise the POST version. The returned structure depends on the searches and the number of searches.

Rows are supported.

$obj->indexes(%options)

[CouchDB API "GET /{db}/_index"]

Collect all indexes for the database. This command supports rows.

$obj->search( $ddoc, $index, [\%search, %options] )

Run a search (Mango or text) on the database. The search base is described in the $index in design document $ddoc. The design document may be specified as id or object.

example: search

# Twice the same
my $r = $db->search(myddoc => myindex => \%search);
my $r = $db->design('myddoc')->search(myindex => \%search);

Handling documents

$obj->allDocs( [\%query|\@queries], %options] )

[CouchDB API "GET /{db}/_all_docs"]
[CouchDB API "POST /{db}/_all_docs"]
[CouchDB API "POST /{db}/_all_docs/queries", UNTESTED]
[CouchDB API "GET /{db}/_local_docs", UNTESTED]
[CouchDB API "POST /{db}/_local_docs", UNTESTED]
[CouchDB API "POST /{db}/_local_docs/queries", UNTESTED]
[CouchDB API "GET /{db}/_partition/{partition}/_all_docs", UNTESTED]

Get the documents, optionally limited by a view. If there are queries, then POST is used, otherwise the GET endpoint.

The returned structure depends on the %query and the number of @queries (an ARRAY of query HASHes). This method support pagination, but only when a single query is given.

The preferred way to use this method with a view, is by calling Couch::DB::Design::viewDocs() on its design object.

-Option   --Default
 design     undef
 local      false
 partition  undef
 view       undef

design => $design|$ddocid: Usually called via Couch::DB::Design::viewDocs().
local => BOOLEAN: Search only in local (non-replicated) documents. This does not support a combination with partition or view.
partition => $name: Restrict the search to the specific partition.
view => $name: Restrict the search to the named view. Requires the design document.

example: getting all documents in a database

Be warned: doing it this way is memory hungry: better use paging.

my $all  = $couch->db('users')->allDocs({include_docs => 1}, all => 1);
my $rows = $all->page;
my @docs = map $_->doc, @$rows;

$obj->doc($docid, %options)

Returns a Couch::DB::Document for this $docid. Be aware that this does not have any interaction with the CouchDB server. Only when you call actions, like exists(), on that object, you can see the status and content of the document.

All %options are passed to Couch::DB::Database::new(). Of course, you do not need to pass the Couch::DB::Database object explicitly.

$obj->find( [\%search, %options] )

[CouchDB API "POST /{db}/_find"]
[CouchDB API "POST /{db}/_partition/{partition_id}/_find", UNTESTED]

Search the database for matching documents, using Mango selectors. The documents are always included in the reply, including attachment information. Attachment data is not included.

The default search will select everything (uses a blank HASH as required selector). By default, the number of results has a limit of 25. Pass limit and skip in %options with other pagination control, not in %search.

-Option   --Default
 partition  undef

partition => $partition

example: of find() with a single query

my $result = $couch->find or die;
my @docs   = $result->docs;  # Couch::DB::Documents
foreach my $doc (@docs) { ... }

$obj->findExplain(\%search, %options)

[CouchDB API "POST /{db}/_explain"]
[CouchDB API "POST /{db}/_partition/{partition_id}/_explain", UNTESTED]

Explain how the a search will be executed.

-Option   --Default
 partition  undef

partition => $partition

$obj->inspectDocs(\@docs, %options)

[CouchDB API "POST /{db}/_bulk_get", UNTESTED]

Return information on multiple documents at the same time.

-Option--Default
 revs    false

revs => BOOLEAN: Include the revision history of each document.

$obj->saveBulk(\@docs, %options)

[CouchDB API "POST /{db}/_bulk_docs"]

Insert, update, and delete multiple documents in one go. This is more efficient than saving them one by one.

Pass the documents which need to be save/updated in an ARRAY as first argument.

-Option   --Default
 delete     [ ]
 issues     undef
 new_edits  true

delete => $doc|\@docs: List of documents to remove. You should not call the delete() method on them yourself!
issues => CODE: By default, missing reports are ignored. When a CODE is specified, it will be called with the result object, the failing document, and named parameters error details. The %details contain the error type, the error reason, and the optional deleting boolean boolean.
new_edits => BOOLEAN: When false, than the docs will replace the existing revisions.

example: bulk adding documents

my $doc1 = $db->doc('new1', content => $data1);
my $doc2 = $db->doc('new2', content => $data2);
$db->saveBulk([$doc1, $doc2]);

example: deleting a document

Can be combined with added documents.

my $del1 = $db->doc('victim');
$db->saveBulk([], delete => $del1);

example: for error handling

sub handle($result, $doc, %details) { ... }
$db->saveBulk(@save, issues => \&handle);

LICENSE

Copyrights 2024-2025 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/

To install Couch::DB, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Couch::DB

CPAN shell

perl -MCPAN -e shell
install Couch::DB

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)