Provisioning Cluster Resources

Provisioning cluster resources is managed at the collection or bucket level, depending upon the service affected. Common use cases are outlined here, less common use cases are covered in the API docs.

The primary means for managing clusters is through the Couchbase Web UI which provides an easy to use interface for adding, removing, monitoring and modifying buckets. In some instances you may wish to have a programmatic interface. For example, if you wish to manage a cluster from a setup script, or if you are setting up buckets in test scaffolding.

The Python SDK also comes with some convenience functionality for common Couchbase management requests.

Management operations in the SDK may be performed through several interfaces depending on the object:

BucketManager — Cluster.Buckets()
UserManager — Cluster.Users()
QueryIndexManager — Cluster.QueryIndexes()
AnalyticsIndexManager — Cluster.AnalyticsIndexes()
SearchIndexManager — Cluster.SearchIndexes()
CollectionManager — Bucket.Collections()
ViewIndexManager — Bucket.ViewIndexes()

When using a Couchbase version earlier than 6.5, you must create a valid Bucket connection using cluster.Bucket(name) before you can use cluster level managers.

Creating and Removing Buckets

The BucketManager interface may be used to create and delete buckets from the Couchbase cluster. It is instantiated through the Cluster.buckets() method.

cluster = Cluster(
    "couchbase://localhost",
    authenticator=PasswordAuthenticator(
        "Administrator",
        "password"))
# For Server versions 6.5 or later you do not need to open a bucket here
bucket = cluster.bucket("default")
collection = bucket.default_collection()

bucket_manager = cluster.buckets()

The CreateBucketSettings and BucketSettings classes are used for creating and updating buckets, BucketSettings is also used for exposing information about existing buckets.

Note that any property that is not explicitly set when building the BucketSettings will use the default value. In the case of the update, this is not necessarily the currently configured value, so you should be careful to set all properties to their correct expected values when updating an existing bucket configuration.

Here is the list of parameters available:

Name

Type

Description

Can be updated

name

str

The name of the bucket, required for creation.

false

flush_enabled

bool

Enables flushing to be performed on this bucket (see the Flushing Buckets section below).

true

replica_index

bool

Whether or not to replicate indexes.

false

ram_quota_mb

int

How much memory should each node use for the bucket, required for creation.

true

num_replicas

int

The number of replicas to use for the bucket.

true

bucket_type

BucketType

The type of the bucket, required for creation.

false

eviction_policy

EvictionPolicyType

The type of the eviction to use for the bucket, defaults to valueOnly.

true (note: changing will cause the bucket to restart causing temporary inaccessibility)

max_ttl

timedelta

The default maximum time-to-live to apply to documents in the bucket. (note: This option is only available for Couchbase and Ephemeral buckets in Couchbase Enterprise Edition.)

true

compression_mode

CompressionMode

The compression mode to apply to documents in the bucket. (note: This option is only available for Couchbase and Ephemeral buckets in Couchbase Enterprise Edition.)

true

conflict_resolution_type

ConflictResolutionType

The conflict resolution type to apply to conflicts on the bucket, defaults to seqno

false

The following example creates a "hello" bucket:

bucket_manager.create_bucket(
    CreateBucketSettings(
        name="hello",
        flush_enabled=False,
        ram_quota_mb=100,
        num_replicas=0,
        bucket_type=BucketType.COUCHBASE,
        conflict_resolution_type=ConflictResolutionType.SEQUENCE_NUMBER))

We can now get this bucket and update it to enable Flush:

bucket = bucket_manager.get_bucket("hello")
print("Found bucket: {}".format(bucket.name))

bucket_manager.update_bucket(BucketSettings(name="hello", flush_enabled=True))

Once you no longer need to use the bucket, you can remove it:

bucket_manager.drop_bucket("hello")

Flushing Buckets

When a bucket is flushed, all content is removed. Because this operation is potentially dangerous it is disabled by default for each bucket. Bucket flushing may be useful in test environments where it becomes a simpler alternative to removing and creating a test bucket. You may enable bucket flushing on a per-bucket basis using the Couchbase Web Console or when creating a bucket.

You can flush a bucket in the SDK by using the flush_bucket() method.

bucket_manager.flush_bucket("hello")

The flush_bucket() operation may fail if the bucket does not have flush enabled, in that case it will return an BucketNotFlushableException.

Collection Management

The CollectionManager interface may be used to create and delete scopes and collections from the Couchbase cluster. It is instantiated through the Bucket.collections() method. Refer to the API documentation for further details.

bucket = cluster.bucket("travel-sample")
coll_manager = bucket.collections()

Creating and Deleting Scopes and Collections

You can create a scope:

try:
    coll_manager.create_scope("example-scope")
except ScopeAlreadyExistsException as ex:
    print(ex)

You can then create a collection within that scope:

collection_spec = CollectionSpec(
    "example-collection",
    scope_name="example-scope")

try:
    collection = coll_manager.create_collection(collection_spec)
except CollectionAlreadyExistsException as ex:
    print(ex)

Finally, you can drop unneeded collections and scopes:

try:
    coll_manager.drop_collection(collection_spec)
except CollectionNotFoundException as ex:
    print(ex)

try:
    coll_manager.drop_scope("example-scope")
except ScopeNotFoundException as ex:
    print(ex)

Note that the most minimal permissions to create and drop a Scope or Collection is Manage Scopes along with Data Reader.

You can create users with the appropriate RBAC programmatically:

users = cluster.users()
user = User(username="scopeAdmin",
            password="password",
            display_name="Manage Scopes [travel-sample:*]",
            roles=[
                Role(name="scope_admin", bucket="travel-sample"),
                Role(name="data_reader", bucket="travel-sample")
            ])
users.upsert_user(user)

Listing the Scopes and Collections available

You can enumerate Scopes and Collections using the CollectionManager.get_all_scopes() method and the Scope.collections property.

def get_scope(collection_mgr, scope_name):
    return next((s for s in collection_mgr.get_all_scopes()
                if s.name == scope_name), None)


def get_collection(collection_mgr, scope_name, coll_name):
    scope = get_scope(collection_mgr, scope_name)
    if scope:
        return next(
            (c for c in scope.collections if c.name == coll_name),
            None)

    return None

Index Management

In general,you will rarely need to work with Index Managers from the SDK. For those occasions when you do, please see the relevant API docs:

QueryIndexManager — Cluster.QueryIndexes();
AnalyticsIndexManager — Cluster.AnalyticsIndexes();
SearchIndexManager — Cluster.SearchIndexes();
ViewIndexManager — Bucket.ViewIndexes().

View Management

Views are stored in design documents. The SDK provides convenient methods to create, retrieve, and remove design documents. To set up views, you create design documents that contain one or more view definitions, and then insert the design documents into a bucket. Each view in a design document is represented by a name and a set of MapReduce functions. The mandatory map function describes how to select and transform the data from the bucket, and the optional reduce function describes how to aggregate the results.

In the SDK, design documents are represented by the DesignDocument and View classes. All operations on design documents are performed on the ViewIndexManager instance:

cluster = Cluster(
    "couchbase://localhost",
    authenticator=PasswordAuthenticator(
        "Administrator",
        "password"))

# For Server versions 6.5 or later you do not need to open a bucket here
bucket = cluster.bucket("travel-sample")

view_manager = bucket.view_indexes()

The following example upserts a design document with two views:

design_doc = DesignDocument(
    name="landmarks",
    views={
        "by_country": View(
            map="function (doc, meta) { if (doc.type == 'landmark') { emit([doc.country, doc.city], null); } }"),
        "by_activity": View(
            map="function (doc, meta) { if (doc.type == 'landmark') { emit(doc.activity, null); } }",
            reduce="_count")})

view_manager.upsert_design_document(
    design_doc, DesignDocumentNamespace.DEVELOPMENT)

When you want to update an existing document with a new view (or a modification of a view’s definition), you can use the upsertDesignDocument method.

However, this method needs the list of views in the document to be exhaustive, meaning that if you just create the new view definition as previously and add it to a new DesignDocument that you upsert, all your other views will be erased!

The solution is to perform a getDesignDocument, add your view definition to the DesignDocument’s views list, then upsert it. This also works with view modifications, provided the change is in the map or reduce functions (just reuse the same name for the modified View), or for deletion of one out of several views in the document.

Note the use of DesignDocumentNamespace.DEVELOPMENT, the other option is DesignDocumentNamespace.PRODUCTION. This parameter specifies whether the design document should be created as development, or as production — with the former running over only a small fraction of the documents.

Now that we’ve created a design document we can fetch it:

d_doc = view_manager.get_design_document(
    "landmarks", DesignDocumentNamespace.DEVELOPMENT)

print("Found design doc: {} w/ {} views.".format(d_doc.name, len(d_doc.views)))

We’ve created the design document using DesignDocumentNamespace.DEVELOPMENT and now want to push it to production, we can do this with:

view_manager.publish_design_document("landmarks")

To remove this design document:

view_manager.drop_design_document(
    "landmarks", DesignDocumentNamespace.DEVELOPMENT)