A newer version of this documentation is available.

View Latest

Managing clusters

You can manage Couchbase clusters programmatically from the Java SDK by using a ClusterManager object.

The ClusterManager class provides methods to create, update, and remove buckets.

Accessing the ClusterManager

To perform cluster-level management tasks, you need to get a reference to the ClusterManager object. It can be accessed through the Cluster, but you need to provide administrative credentials:

Cluster cluster = CouchbaseCluster.create("127.0.0.1");
ClusterManager clusterManager = cluster.clusterManager("Administrator", "password");

The ClusterManager class provides methods that enable you to retrieve information about the cluster state and manage buckets in the cluster:

Table 1. ClusterManager methods
Method Description

info

Provides cluster information

getBuckets

Lists all buckets with their settings from the cluster

getBucket

Gets a bucket with its settings from the cluster

hasBucket

Checks if a bucket exists or not on the cluster

insertBucket

Creates a new bucket on the cluster

updateBucket

Updates a bucket on the cluster

removeBucket

Removes a bucket from the cluster

Cluster information

When you call ClusterManager#info() it returns a ClusterInfo object that contains both raw and typed information on the overall cluster state. In addition to the ClusterInfo#raw() method that provides direct access to everything returned by the server, the following methods are available:

  • To find out the minimum version of all nodes in the cluster, you can use the ClusterInfo#getMinVersion() method. For example, if you have 3 nodes running version 3.1 and one running version 3.0.3, it reports version 3.0.3.

  • If you want to check if a certain feature is enabled on the cluster, you can use the checkAvailable method and pass in one of theCouchbaseFeature enumerations. It uses the minimum cluster version as a basis and then asserts it against the minimum version of the passed in feature. The SDK uses this internally to determine if specific integration tests can be executed against the connected cluster, and so can you.

  • The getAllVersions method returns the version number of all nodes in the cluster.

Bucket management

To create a bucket, first define the bucket attributes in a BucketSettings object, and then pass it to the insertBucket() method:

new DefaultBucketSettings.Builder()
    .type(BucketType.COUCHBASE)
    .name("hello")
    .password("s3cret")
    .quota(100) // megabytes
    .replicas(0)
    .indexReplicas(false)
    .enableFlush(false)
    .build();

manager.insertBucket(bucketSettings);

The name and quota properties are mandatory. By default, the type of the bucket is BucketType.COUCHBASE.

All properties of a bucket except the name and type can be updated programmatically via the BucketSettings object. If you omit a property from theBucketSettings object, the default value for the omitted property is used.

To avoid any inadvertent changes to bucket properties, make sure to set all properties in the BucketSettings object regardless of whether you are changing the value or continuing to use the existing value:

BucketSettings bucketSettings = new DefaultBucketSettings.Builder()
    .type(BucketType.COUCHBASE)
    .name("hello")
    .password("")
    .quota(120) // megabytes
    .replicas(1)
    .indexReplicas(true)
    .enableFlush(true)
    .build();

manager.updateBucket(bucketSettings);

To remove a bucket, pass its name to the removeBucket() method.

manager.removeBucket("hello");

Since all of the bucket management methods require you to deal with BucketSettings, here is a reference table:

Table 2. BucketSettings methods
Method Description

name

The name of the bucket

type

The type of the bucket (couchbase or memcached)

quota

The bucket quota

port

The optional proxy port

password

The password of the bucket

replicas

The number of replicas

indexReplicas

The number of index replicas

enableFlush

If flush is enabled or not