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( [\%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 theGET
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::viewSearch() on itsdesign
object.-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.006, built on September 09, 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/