NAME
Couch::DB::Database - One database connection
SYNOPSIS
my $db = Couch::DB->db('my-db');
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
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
- $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 returnsHTTP_PRECONDITION_FAILED
and an error in the body.Options:
partitioned
(bool),q
(number of shards, default 8), andn
(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
- $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->purgeRecordsLimit(%options)
-
[CouchDB API "GET /{db}/_purged_infos_limit", UNTESTED]
Returns the soft maximum number of records kept about deleting records.
- $obj->purgeRecordsLimitSet($limit, %options)
-
[CouchDB API "PUT /{db}/_purged_infos_limit", UNTESTED]
Set a new soft limit. The default is 1000.
- $obj->purgeUnusedViews(%options)
-
[CouchDB API "POST /{db}/_view_cleanup", UNTESTED]
Removes view files that are not used by any design document.
- $obj->remove(%options)
-
[CouchDB API "DELETE /{db}"]
Remove the database.
- $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 [ ]
Designs and Indexes
- $obj->createIndex(\%filter, %options)
-
[CouchDB API "POST /{db}/_index", UNTESTED] Create/confirm an index on the database. By default, the index C<name> and the name for the design document C<ddoc> are generated. You can also call C<Couch::DB::Design::createIndex()>. -Option--Default design undef
- $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 thePOST
version. The returned structure depends on the searches and the number of searches. - $obj->indexes(%options)
-
[CouchDB API "GET /{db}/_index", UNTESTED]
Collect all indexes for the database.
Handling documents
- $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, likeexists()
, 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 theCouch::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. The documents are always included in the reply, including attachment information. Attachement data is not included.
The default search will select everything (uses a blank HASH as required
selector
). By default, the number of results has alimit
of 25. j Passlimit
andskip
in%options
with other pagination control, not in%search
.-Option --Default partition undef
example: of find() with a single query
my $result = $couch->find or die; my $docs = $result->values->{docs}; # Couch::DB::Documents foreach my $doc (@$docs) { ... }
example: of find() more than one query:
my $result = $couch->find( [\%q0, \%q1] ) or die; my $docs = $result->values->{results}[1]{docs}; 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
- $obj->inspectDocs(\@docs, %options)
-
[CouchDB API "POST /{db}/_bulk_get", UNTESTED]
Return information on multiple documents at the same time.
-Option--Default revs false
- $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 errorreason
, and the optionaldeleting
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);
- $obj->search( [\%search|\@%search, %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 searches, then
POST
is used, otherwise theGET
version. The returned structure depends on the searches and the number of searches. Of course, this method support pagination.The usual way to use this method with a view, is by calling Couch::DB::Design::viewSearch().
-Option --Default design undef local false partition undef view undef
- design => $design|$ddocid
-
Usually called via Couch::DB::Design::viewSearch().
- local => BOOLEAN
-
Search only in local (non-replicated) documents. This does not support a combination with
partition
orview
. - 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')->search({include_docs => 1}, _all => 1); my $hits = $all->page; my @docs = map $_->{doc}, @$hits;
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/