Management

Note

Further updates to the management API docs will come with future 4.0.x releases.

Bucket Management

class couchbase.management.buckets.BucketManager(connection)
create_bucket(settings, *options, **kwargs) → None

Creates a new bucket.

Parameters:

  • settings (CreateBucketSettings) – The settings to use for the new bucket.

  • options (CreateBucketOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

  • BucketAlreadyExistsException – If the bucket already exists.

  • InvalidArgumentsException – If an invalid type or value is provided for the settings argument.

drop_bucket(bucket_name, *options, **kwargs) → None

Drops an existing bucket.

Parameters:

  • bucket_name (str) – The name of the bucket to drop.

  • options (DropBucketOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

BucketDoesNotExistException – If the bucket does not exist.

flush_bucket(bucket_name, *options, **kwargs) → None

Flushes the bucket, deleting all the existing data that is stored in it.

Parameters:

  • bucket_name (str) – The name of the bucket to flush.

  • options (FlushBucketOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

  • BucketDoesNotExistException – If the bucket does not exist.

  • BucketNotFlushableException – If the bucket’s settings have flushing disabled.

get_all_buckets(*options, **kwargs) → List[BucketSettings]

Returns a list of existing buckets in the cluster.

Parameters:

  • options (GetAllBucketOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Returns:

A list of existing buckets in the cluster.

Return type:

List[BucketSettings]

get_bucket(bucket_name, *options, **kwargs) → BucketSettings

Fetches the settings in use for a specified bucket.

Parameters:

  • bucket_name (str) – The name of the bucket to fetch.

  • options (GetBucketOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Returns:

The settings of the specified bucket.

Return type:

BucketSettings

Raises:

BucketDoesNotExistException – If the bucket does not exist.

update_bucket(settings, *options, **kwargs) → None

Update the settings for an existing bucket.

Parameters:

  • settings (BucketSettings) – The settings to use for the new bucket.

  • options (UpdateBucketOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

InvalidArgumentsException – If an invalid type or value is provided for the settings argument.

Collection Management

class couchbase.management.collections.CollectionManager(connection, bucket_name)
create_collection(collection: CollectionSpec, *options: CreateCollectionOptions, **kwargs: Dict[str, Any]) → None

Deprecated since version 4.1.9: Use create_collection(scope_name, collection_name, settings=None, *options, **kwargs) instead.

Creates a new collection in a specified scope.

Parameters:

  • collection (CollectionSpec) – The collection details.

  • *options (CreateCollectionOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

  • CollectionAlreadyExistsException – If the collection already exists.

  • ScopeNotFoundException – If the scope does not exist.

create_collection(scope_name: str, collection_name: str, settings: CreateCollectionSettings | None = None, *options: CreateCollectionOptions, **kwargs: Dict[str, Any]) → None

Creates a new collection in a specified scope.

Parameters:

  • scope_name (str) – The name of the scope the collection will be created in.

  • collection_name (str) – The name of the collection to be created

  • settings (CreateCollectionSettings, optional) – Settings to apply for the collection

  • options (CreateCollectionOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

  • CollectionAlreadyExistsException – If the collection already exists.

  • ScopeNotFoundException – If the scope does not exist.

create_scope(scope_name: str, *options: CreateScopeOptions, **kwargs: Dict[str, Any]) → None

Creates a new scope.

Parameters:

  • scope_name (str) – The name of the scope.

  • options (CreateScopeOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

ScopeAlreadyExistsException – If the scope already exists.

drop_collection(collection: CollectionSpec, *options: DropCollectionOptions, **kwargs: Dict[str, Any]) → None

Deprecated since version 4.1.9: Use drop_collection(scope_name, collection_name, *options, **kwargs) instead.

Drops a collection from a specified scope.

Parameters:

  • collection (CollectionSpec) – The collection details.

  • *options (DropCollectionOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

CollectionNotFoundException – If the collection does not exist.

drop_collection(scope_name: str, collection_name: str, *options: DropCollectionOptions, **kwargs: Dict[str, Any]) → None

Drops a collection from the specified scope.

Parameters:

  • scope_name (str) – The name of the scope the collection is in.

  • collection_name (str) – The name of the collection to be dropped

  • options (DropCollectionOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

CollectionNotFoundException – If the collection does not exist.

drop_scope(scope_name: str, *options: DropScopeOptions, **kwargs: Dict[str, Any]) → None

Drops an existing scope.

Parameters:

  • scope_name (str) – The name of the scope.

  • options (DropScopeOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

ScopeNotFoundException – If the scope does not exist.

get_all_scopes(*options: GetAllScopesOptions, **kwargs: Dict[str, Any]) → Iterable[ScopeSpec]

Returns all configured scopes along with their collections.

Parameters:

  • scope_name (str) – The name of the scope.

  • options (GetAllScopesOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Returns:

A list of all configured scopes.

Return type:

Iterable[ScopeSpec]

class couchbase.management.collections.CollectionSpec(collection_name, scope_name='_default', max_expiry=None, max_ttl=None, history=None)
property name: str

The name of the collection

Type:

str

property scope_name: str

The name of the collection’s scope

Type:

str

property max_ttl: timedelta | None

DEPRECATED Optional[timedelta]: The expiry for documents in the collection.

class couchbase.management.collections.ScopeSpec(name, collections)
property name: str

The name of the scope

Type:

str

property collections: Iterable[CollectionSpec]

A list of the scope’s collections.

Type:

List[CollectionSpec]

Query Index Management

class couchbase.management.queries.QueryIndexManager(connection)
build_deferred_indexes(bucket_name, *options, **kwargs) → None

Starts building any indexes which were previously created with deferred=True.

Parameters:

  • bucket_name (str) – The name of the bucket to perform build on.

  • options (BuildDeferredQueryIndexOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

InvalidArgumentException – If the bucket_name is an invalid type.

create_index(bucket_name, index_name, keys, *options, **kwargs) → None

Creates a new query index.

Parameters:

  • bucket_name (str) – The name of the bucket this index is for.

  • index_name (str) – The name of the index.

  • keys (Iterable[str]) – The keys which this index should cover.

  • options (CreateQueryIndexOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

  • InvalidArgumentException – If the bucket_name, index_name or keys are invalid types.

  • QueryIndexAlreadyExistsException – If the index already exists.

create_primary_index(bucket_name, *options, **kwargs) → None

Creates a new primary query index.

Parameters:

  • bucket_name (str) – The name of the bucket this index is for.

  • options (CreatePrimaryQueryIndexOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

  • InvalidArgumentException – If the bucket_name is an invalid type.

  • QueryIndexAlreadyExistsException – If the index already exists.

drop_index(bucket_name, index_name, *options, **kwargs) → None

Drops an existing query index.

Parameters:

  • bucket_name (str) – The name of the bucket containing the index to drop.

  • index_name (str) – The name of the index to drop.

  • options (DropQueryIndexOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

  • InvalidArgumentException – If the bucket_name or index_name are invalid types.

  • QueryIndexNotFoundException – If the index does not exists.

drop_primary_index(bucket_name, *options, **kwargs) → None

Drops an existing primary query index.

Parameters:

  • bucket_name (str) – The name of the bucket this index to drop.

  • options (DropPrimaryQueryIndexOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

  • InvalidArgumentException – If the bucket_name is an invalid type.

  • QueryIndexNotFoundException – If the index does not exists.

get_all_indexes(bucket_name, *options, **kwargs) → Iterable[QueryIndex]

Returns a list of indexes for a specific bucket.

Parameters:

  • bucket_name (str) – The name of the bucket to fetch indexes for.

  • options (GetAllQueryIndexOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Returns:

A list of indexes for a specific bucket.

Return type:

Iterable[QueryIndex]

Raises:

InvalidArgumentException – If the bucket_name is an invalid type.

watch_indexes(bucket_name, index_names, *options, **kwargs) → None

Waits for a number of indexes to finish creation and be ready to use.

Parameters:

  • bucket_name (str) – The name of the bucket to watch for indexes on.

  • index_names (Iterable[str]) – The names of the indexes to watch.

  • options (WatchQueryIndexOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

  • InvalidArgumentException – If the bucket_name or index_names are invalid types.

  • WatchQueryIndexTimeoutException – If the specified timeout is reached before all the specified indexes are ready to use.

User Management

class couchbase.management.users.UserManager(connection)
drop_user(username, *options, **kwargs) → None

Drops an existing user.

Parameters:

  • username (str) – The name of the user to drop.

  • options (DropUserOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

UserNotFoundException – If the user does not exist.

drop_group(group_name, *options, **kwargs) → None

Drops an existing group.

Parameters:

  • group_name (str) – The name of the group to drop.

  • options (DropGroupOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

GroupNotFoundException – If the group does not exist.

get_all_groups(*options, **kwargs) → Iterable[Group]

Returns a list of all existing groups.

Parameters:

  • options (GetAllGroupsOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Returns:

A list of existing groups.

Return type:

Iterable[Group]

get_all_users(*options, **kwargs) → Iterable[UserAndMetadata]

Returns a list of all existing users.

Parameters:

  • options (GetAllUsersOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Returns:

A list of existing users.

Return type:

Iterable[UserAndMetadata]

get_group(group_name, *options, **kwargs) → Group

Returns a group by it’s name.

Parameters:

  • group_name (str) – The name of the group to retrieve.

  • options (GetGroupOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Returns:

A Group instance.

Return type:

Group

Raises:

GroupNotFoundException – If the group does not exist.

get_roles(*options, **kwargs) → Iterable[RoleAndDescription]

Returns a list of roles available on the server.

Parameters:

  • options (GetRolesOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Returns:

A list of roles available on the server.

Return type:

Iterable[RoleAndDescription]

get_user(username, *options, **kwargs) → UserAndMetadata

Returns a user by its username.

Parameters:

  • username (str) – The name of the user to retrieve.

  • options (GetUserOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Returns:

A UserAndMetadata instance.

Return type:

UserAndMetadata

Raises:

UserNotFoundException – If the user does not exist.

upsert_group(group, *options, **kwargs) → None

Creates a new group or updates an existing group.

Parameters:

  • group (Group) – The group to create or update.

  • options (UpsertGroupOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

InvalidArgumentException – If the provided group argument contains an invalid value or type.

upsert_user(user, *options, **kwargs) → None

Creates a new user or updates an existing user.

Parameters:

  • user (User) – The user to create or update.

  • options (UpsertUserOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used as optional parameters for this operation.

Raises:

InvalidArgumentException – If the provided user argument contains an invalid value or type.