Administrative Operations

The Admin provides several convenience methods to perform common API requests.

Warning

The interface here is provided as a convenience only and its interface may change.

To create an administrative handle, simply instantiate a new Admin object. Note that unlike the Bucket, the Admin constructor does not accept a connection string. This is deliberate, as the administrative API communicates with a single node, on a well defined port (whereas the Bucket object communicates with one or more nodes using a variety of different protocols).

class couchbase_core.admin.Admin(username, password, host='localhost', port=8091, **kwargs)[source]

An administrative connection to a Couchbase cluster.

With this object, you can do things which affect the cluster, such as modifying buckets, allocating nodes, or retrieving information about the cluster.

This object should not be used to perform Key/Value operations. The Bucket is used for that.

Connect to a cluster

Parameters

  • username (string) – The administrative username for the cluster, this is typically Administrator

  • password (string) – The administrative password for the cluster, this is the password you entered when Couchbase was installed

  • host (string) – The hostname or IP of one of the nodes which is currently a member of the cluster (or a newly allocated node, if you wish to operate on that)

  • port (int) – The management port for the node

Raise

couchbase_core.exceptions.AuthError if incorrect credentials were supplied

couchbase_core.exceptions.ConnectError if there was a problem establishing a connection to the provided host

Returns

an instance of Admin

class BucketInfo(raw_json)[source]

Information about a bucket

name()[source]

Name of the bucket. :return: A str containing the bucket name.

bucket_create(name, bucket_type='couchbase', bucket_password='', replicas=0, ram_quota=1024, flush_enabled=False)[source]

Create a new bucket

Parameters

  • name (string) – The name of the bucket to create

  • bucket_type (string) – The type of bucket to create. This can either be couchbase to create a couchbase_core style bucket (which persists data and supports replication) or memcached (which is memory-only and does not support replication). Since Couchbase version 5.0, you can also specify ephemeral, which is a replicated bucket which does not have strict disk persistence requirements

  • bucket_password (string) – The bucket password. This can be empty to disable authentication. This can be changed later on using bucket_update()

  • replicas (int) – The number of replicas to use for this bucket. The maximum number of replicas is currently 3. This setting can be changed via bucket_update()

  • ram_quota (int) – The maximum amount of memory (per node) that this bucket may use, in megabytes. The minimum for this value is 100. This setting may be changed via bucket_update().

  • flush_enabled (bool) – Whether the flush API is enabled. When the flush API is enabled, any client connected to the bucket is able to clear its contents. This may be useful in development but not recommended in production. This setting may be changed via bucket_update()

Returns

A HttpResult

Raise

HTTPError if the bucket could not be created.

bucket_delete(name)

Remove an existing bucket from the cluster

Parameters

name (string) – The name of the bucket to remove

Returns

A HttpResult

Raise

HTTPError on error

bucket_info(name)[source]

Retrieve information about the bucket.

Parameters

name (string) – The name of the bucket

Returns

A HttpResult object. The result’s value attribute contains A dictionary containing the bucket’s information. The returned object is considered to be opaque, and is intended primarily for use with bucket_update(). Currently this returns the raw decoded JSON as emitted by the corresponding server-side API

Raise

HTTPError if the request failed

bucket_remove(name)[source]

Remove an existing bucket from the cluster

Parameters

name (string) – The name of the bucket to remove

Returns

A HttpResult

Raise

HTTPError on error

bucket_update(name, current, bucket_password=None, replicas=None, ram_quota=None, flush_enabled=None)[source]

Update an existing bucket’s settings.

Parameters

  • name (string) – The name of the bucket to update

  • current (dict) – Current state of the bucket. This can be retrieve from bucket_info()

  • bucket_password (str) – Change the bucket’s password

  • replicas (int) – The number of replicas for the bucket

  • ram_quota (int) – The memory available to the bucket on each node.

  • flush_enabled (bool) – Whether the flush API should be allowed from normal clients

Returns

A HttpResult object

Raise

HTTPError if the request could not be completed

Note

The default value for all options in this method is None. If a value is set to something else, it will modify the setting.

Change the bucket password:

adm.bucket_update('a_bucket', adm.bucket_info('a_bucket'),
                  bucket_password='n3wpassw0rd')

Enable the flush API:

adm.bucket_update('a_bucket', adm.bucket_info('a_bucket'),
                  flush_enabled=True)
buckets_list()[source]

Retrieve the list of buckets from the server :return: An iterable of Admin.BucketInfo objects describing the buckets currently active on the cluster.

get_user(domain, userid)

Retrieve a user from the server

Parameters

  • domain (AuthDomain) – The authentication domain for the user.

  • userid – The user ID.

Raise

couchbase_core.exceptions.HTTPError if the user does not exist.

Returns

HttpResult. The user can be obtained from the returned object’s value property.

get_users(domain)

Retrieve a list of users from the server.

Parameters

domain (AuthDomain) – The authentication domain to retrieve users from.

Returns

HttpResult. The list of users can be obtained from the returned object’s value property.

http_request(path, method='GET', content=None, content_type='application/json', response_format=33554432)[source]

Perform an administrative HTTP request. This request is sent out to the administrative API interface (i.e. the “Management/REST API”) of the cluster.

Note that this is a fairly low level function. You should use one of the helper methods in this class to perform your task, if possible.

Parameters

  • path (string) – The path portion (not including the host) of the rest call to perform. This should also include any encoded arguments.

  • method (string) – This is the HTTP method to perform. Currently supported values are GET, POST, PUT, and DELETE

  • content (bytes) – Content to be passed along in the request body. This is only applicable on PUT and POST methods.

  • content_type (string) – Value for the HTTP Content-Type header. Currently this is application-json, and should probably not be set to something else.

  • response_format (int) –

    Hint about how to format the response. This goes into the value field of the HttpResult object. The default is FMT_JSON.

    Note that if the conversion fails, the content will be returned as bytes

Raise
ArgumentError

if the method supplied was incorrect.

ConnectError

if there was a problem establishing a connection.

HTTPError

if the server responded with a negative reply

Returns

a HttpResult object.

See also

bucket_create(), bucket_remove()

remove_user(domain, userid)

Remove a user :param AuthDomain domain: The authentication domain for the user. :param userid: The user ID to remove :raise: couchbase_core.exceptions.HTTPError if the user does not exist. :return: HttpResult

upsert_user(domain, userid, password=None, roles=None, name=None)

Upsert a user in the cluster

Parameters

  • domain (AuthDomain) – The authentication domain for the user.

  • userid – The user ID

  • password – The user password

  • roles – A list of roles. A role can either be a simple string, or a list of (role, bucket) pairs.

  • name – Human-readable name

Raise

couchbase_core.exceptions.HTTPError if the request fails.

Returns

HttpResult

Creating a new read-only admin user

adm.upsert_user(AuthDomain.Local, 'mark', 's3cr3t', ['ro_admin'])

An example of using more complex roles

adm.upsert_user(AuthDomain.Local, 'mark', 's3cr3t',
                                  [('data_reader', '*'),
                                   ('data_writer', 'inbox')])

Warning

Due to the asynchronous nature of Couchbase management APIs, it may take a few moments for the new user settings to take effect.

user_get(domain, userid)[source]

Retrieve a user from the server

Parameters

  • domain (AuthDomain) – The authentication domain for the user.

  • userid – The user ID.

Raise

couchbase_core.exceptions.HTTPError if the user does not exist.

Returns

HttpResult. The user can be obtained from the returned object’s value property.

user_remove(domain, userid)[source]

Remove a user :param AuthDomain domain: The authentication domain for the user. :param userid: The user ID to remove :raise: couchbase_core.exceptions.HTTPError if the user does not exist. :return: HttpResult

user_upsert(domain, userid, password=None, roles=None, name=None)[source]

Upsert a user in the cluster

Parameters

  • domain (AuthDomain) – The authentication domain for the user.

  • userid – The user ID

  • password – The user password

  • roles – A list of roles. A role can either be a simple string, or a list of (role, bucket) pairs.

  • name – Human-readable name

Raise

couchbase_core.exceptions.HTTPError if the request fails.

Returns

HttpResult

Creating a new read-only admin user

adm.upsert_user(AuthDomain.Local, 'mark', 's3cr3t', ['ro_admin'])

An example of using more complex roles

adm.upsert_user(AuthDomain.Local, 'mark', 's3cr3t',
                                  [('data_reader', '*'),
                                   ('data_writer', 'inbox')])

Warning

Due to the asynchronous nature of Couchbase management APIs, it may take a few moments for the new user settings to take effect.

users_get(domain)[source]

Retrieve a list of users from the server.

Parameters

domain (AuthDomain) – The authentication domain to retrieve users from.

Returns

HttpResult. The list of users can be obtained from the returned object’s value property.

wait_ready(name, timeout=5.0, sleep_interval=0.2)[source]

Wait for a newly created bucket to be ready.

Parameters

  • name (string) – the name to wait for

  • timeout (seconds) – the maximum amount of time to wait

  • sleep_interval (seconds) – the number of time to sleep between each probe

Raise

CouchbaseError on internal HTTP error

Raise

NotReadyError if all nodes could not be ready in time