A newer version of this documentation is available.

View Latest

Managing Clusters using the Python SDK with Couchbase Server


    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.

    You may perform Couchbase management operations from any HTTP client (e.g. urllib or requests). The Python SDK also comes with some convenience functionality for common Couchbase management requests.

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

    • couchbase.admin.Admin class

    • couchbase.bucket.BucketManager class (obtained viaBucket.bucket_manager())

    • As a direct API of Bucket

    Creating and removing buckets

    The Admin class may be used to create and delete buckets from the Couchbase cluster. It is instantiated using the administrative username and password, followed by a cluster node.

    from couchbase.admin import Admin
    adm = Admin('Administrator', '123456', host='localhost', port=8091)

    To create a bucket, use the Admin.bucket_create() function, passing the bucket name as the first argument. Other arguments may also be specified using keyword arguments


    Some useful parameters:

    • bucket_type: Defaults to "couchbase", but can also be "memcached" to create a cache bucket

    • ram_quota: How much memory should each node use for the bucket. This number is specified in megabytes

    • bucket_password: If specified, makes this bucket password protected, forcing future connects (using the Bucket) class to specify the password parameter

    • flush_enabled: Enables the Bucket.flush() operation to be performed on this bucket

    Once the bucket has been created, you must wait for it to become ready. This is because the bucket is actually created in the background. You may need to wait some time until the bucket becomes ready by repeatedly trying to connect to it, until it succeeds.

    The Admin class also has a convenience method to wait until the bucket becomes ready

    # Wait for bucket to become ready
    adm.wait_ready('new-bucket', timeout=30)

    You can now create to the bucket

    bucket = Bucket('couchbase://localhost/new-bucket', password='s3cr3t')

    Once you no longer need to use the bucket, you may delete the bucket using the Admin.bucket_remove function:


    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 may flush a bucket in the Python SDK by using the Bucket.flush()


    The flush operation may fail if the bucket does not have flush enabled:

    Traceback (most recent call last):
      File "python/flush.py", line 6, in <module>
      File "/usr/local/lib/python2.7/site-packages/couchbase/bucket.py", line 1715, in flush
        path=path, method=_LCB.LCB_HTTP_METHOD_POST)
    couchbase.exceptions.HTTPError: <Key='/pools/default/buckets/travel-sample/controller/doFlush', RC=0x3B[HTTP Operation failed. Inspect status code for details], HTTP Request failed. Examine 'objextra' for full result, Results=1, C Source=(src/http.c,140), OBJ=HttpResult<rc=0x0, value={u'_': u'Flush is disabled for the bucket'}, http_status=400, url=/pools/default/buckets/travel-sample/controller/doFlush>>

    N1QL Index Management

    You can create and drop N1QL indexes using the SDK. This is especially useful when setting up new applications, or simply when ensuring that a given bucket has certain indexes defined. Indexes can be defined using actual N1QL statements or by using convenience functions within the SDK.

    You can manage indexes in the Python SDK using the BucketManager class

    manager = cb.bucket_manager()

    Design Document Management

    You can create, delete, retrieve, and publish design documents (used for MapReduce views) using the SDK. This is useful when setting up new applications, updating view definitions, or running tests.

    Using the Python SDK you may use the design_* methods of the BucketManager class to modify design documents.

    DESIGN_DOC = {
        'views': {
            'by_zipcode': {
                'map': '''
                function(doc, meta) {
                    if (doc.country && doc.zipcode) {
                        emit([doc.country, doc.zipcode], null)
    mgr.design_create('locations', DESIGN_DOC, use_devmode=True)
    for row in cb.query('locations', 'by_zipcode'):
    mgr.design_delete('locations', use_devmode=False)
    Management APIs are considered to be asynchronous, which means you may need to wait some time (or poll manually) until the design document becomes available. This is done by repeatedly querying the newly created view until it no longer fails with a not found error.

    You can use the use_devmode (the default) parameter to indicate that the view should initially be a development mode view.