/ 
Couch-DB-0.201
River stage zero No dependents
/ Couch::DB::Cluster

NAME

Couch::DB::Cluster - interface for cluster management

SYNOPSIS

my $cluster = $couchdb->cluster;

DESCRIPTION

This modules groups all CouchDB API calls which relate to clustering, replication, sharind, and related jobs. There are too many related methods, so they got their own module.

METHODS

Constructors

$class->new(%options)

Do not call the method yourself: use Couch::DB::cluster().

-Option--Default
 couch   <required>
couch => Couch::DB-object

Accessors

$obj->couch()

Managing a Cluster

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

$obj->clusterSetup($config, %options)
[CouchDB API "POST /_cluster_setup", since 2.0, UNTESTED]

Configure a node as a single (standalone) node, as part of a cluster, or finalise a cluster.

$obj->clusterState(%options)
[CouchDB API "GET /_cluster_setup", since 2.0]

Describes the status of this CouchDB instance is in the cluster. Option ensure_dbs_exist.

Sharding

$obj->reshardJob($jobid, %options)
[CouchDB API "GET /_reshard/jobs/{jobid}", since 2.4, UNTESTED]

Show the resharding activity.

$obj->reshardJobChange($jobid, %options)
 [CouchDB API "PUT /_reshard/jobs/{jobid}/state", since 2.4, UNTESTED]
Change the resharding job status.

-Option--Default
 reason  undef
 state   <required>
reason => STRING
state => STRING

Can be new, running, stopped, completed, or failed.

$obj->reshardJobRemove($jobid, %options)
[CouchDB API "DELETE /_reshard/jobs/{jobid}", since 2.4, UNTESTED]

Show the resharding activity.

$obj->reshardJobState($jobid, %options)
[CouchDB API "GET /_reshard/jobs/{jobid}/state", since 2.4, UNTESTED]

Show the resharding job status.

$obj->reshardJobs(%options)
[CouchDB API "GET /_reshard/jobs", since 2.4]

Show the resharding activity.

$obj->reshardStart(\%create, %options)
[CouchDB API "POST /_reshard/jobs", since 2.4, UNTESTED]

Create resharding jobs.

$obj->reshardStatus(%options)
[CouchDB API "GET /_reshard", since 2.4]
[CouchDB API "GET /_reshard/state", since 2.4]

Retrieve the state of resharding on the cluster.

Be warned that the reply with counts returns state_reason, where the version without returns reason.

-Option--Default
 counts  false
counts => BOOLEAN

Include the job counts in the result.

$obj->resharding(%options)
[CouchDB API "PUT /_reshard/state", since 2.4, UNTESTED]

Start or stop the resharding process.

-Option--Default
 reason  undef
 state   <required>
reason => STRING
state => 'stopped'|'running'

Stopped state can be resumed into running.

$obj->shardsForDB($db, %options)
[CouchDB API "GET /{db}/_shards", since 2.0]

Returns the structure of the shared used to store a database. Pass this a $db as Couch::DB::Database-object.

$obj->shardsForDoc($doc, %options)
[CouchDB API "GET /{db}/_shards/{docid}", since 2.0]

Returns the structure of the shared used to store a database. Pass this a $db as Couch::DB::Database-object.

$obj->syncShards($db, %options)
[CouchDB API "POST /{db}/_sync_shards", since 2.3.1]

Force (re-)sharding of documents, usually in response to changes in the setup. Pass this a $db as Couch::DB::Database-object.

SEE ALSO

This module is part of Couch-DB version 0.201, built on January 30, 2026. Website: http://perl.overmeer.net/CPAN/

LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2024-2026 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.