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 Client, 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 Client object communicates with one or more nodes using a variety of different protocols).

class couchbase.management.admin.Admin(username, password, host='localhost', port=8091, **kwargs)

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 Client is used for that.

Connect to a cluster

param string username

The administrative username for the cluster, this is typically Administrator

param string password

The administrative password for the cluster, this is the password you entered when Couchbase was installed

param string host

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)

param int port

The management port for the node

raise

couchbase.exceptions.AuthenticationException if incorrect credentials were supplied

couchbase.exceptions.ConnectException if there was a problem establishing a connection to the provided host

return

an instance of Admin

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

class BucketInfo(raw_json)

Information about a bucket

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

name()

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

bucket_create(name, **kwargs)

Create a new bucket

param string name

The name of the bucket to create

param string bucket_type

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

param string bucket_password

The bucket password. This can be empty to disable authentication. This can be changed later on using update_bucket()

param int replicas

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

param int ram_quota

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 update_bucket().

param bool flush_enabled

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 update_bucket()

return

A HttpResult

raise

HTTPException if the bucket could not be created.

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

bucket_delete(name)

Remove an existing bucket from the cluster

param string name

The name of the bucket to remove

return

A HttpResult

raise

HTTPException on error

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

bucket_info(name)

Retrieve information about the bucket.

param string name

The name of the bucket

return

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 update_bucket(). Currently this returns the raw decoded JSON as emitted by the corresponding server-side API

raise

HTTPException if the request failed

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

bucket_remove(name)

Remove an existing bucket from the cluster

param string name

The name of the bucket to remove

return

A HttpResult

raise

HTTPException on error

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

buckets_list()

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

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

get_roles(timeout=None)

Retrieve roles from the server

param timeout

time allowed for operation to be terminated. This is controlled by the client.

raise

couchbase.exceptions.HTTPException if the request fails.

return

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

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

group_get(group_name, timeout=None)

Retrieve a group from the server

param group_name

the name of the group to get

raise

couchbase.exceptions.HTTPException if the group does not exist.

return

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

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

group_remove(group_name, **kwargs)

Remove a group

param group_name

the name of the group to get

raise

couchbase.exceptions.HTTPException if the group does not exist.

return

HttpResult

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

group_upsert(group_name, roles=None, description=None, ldap_group_reference=None, timeout=None)

Upsert a group in the cluster

param group_name

The name of the group

param roles

A list of roles

param description

The description of the group

param ldap_group_reference

The external LDAP group reference

param timeout

time allowed for operation to be terminated. This is controlled by the client.

raise

couchbase.exceptions.HTTPException if the request fails.

return

HttpResult

Warning

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

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

groups_get(timeout=None)

Retrieve a list of groups from the server.

raise

couchbase.exceptions.HTTPException if the request fails.

return

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

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

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

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.

param string path

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

param string method

This is the HTTP method to perform. Currently supported values are GET, POST, PUT, and DELETE

param bytes content

Content to be passed along in the request body. This is only applicable on PUT and POST methods.

param string content_type

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

param int response_format

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

InvalidArgumentException

if the method supplied was incorrect.

ConnectException

if there was a problem establishing a connection.

HTTPException

if the server responded with a negative reply

return

a HttpResult object.

See also

bucket_create(), bucket_remove()

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

user_get(username, domain, timeout=None)

Retrieve a user from the server

param username

The user ID.

param AuthDomain domain

The authentication domain for the user.

raise

couchbase.exceptions.HTTPException if the user does not exist.

return

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

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

user_remove(username, domain, timeout=None)

Remove a user

param AuthDomain domain

The authentication domain for the user.

param username

The user ID to remove

raise

couchbase.exceptions.HTTPException if the user does not exist.

return

HttpResult

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

user_upsert(username, domain, password=None, roles=None, groups=None, name=None, timeout=None)

Upsert a user in the cluster

param username

The new username or user to update

param AuthDomain domain

The authentication domain for the user.

param password

The user password

param roles

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

param name

role display name

param timeout

time allowed for operation to be terminated. This is controlled by the client.

raise

couchbase.exceptions.HTTPException if the request fails.

return

HttpResult

Creating a new read-only admin user

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

An example of using more complex roles

adm.user_upsert(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.

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

users_get(domain, timeout=None)

Retrieve a list of users from the server.

param AuthDomain domain

The authentication domain to retrieve users from.

return

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

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.

wait_ready(name, timeout=5.0, sleep_interval=0.2)

Wait for a newly created bucket to be ready.

param string name

the name to wait for

param seconds timeout

the maximum amount of time to wait

param seconds sleep_interval

the number of time to sleep between each probe

raise

CouchbaseException on internal HTTP error

raise

NotReadyException if all nodes could not be ready in time

Warning

This is an internal API call.

Components external to Couchbase Python Client should not rely on it is not intended for use outside the module, even to other Couchbase components.