Buckets

class couchbase.management.buckets.BucketDescribeResult(name: str | None = None, uuid: str | None = None, number_of_nodes: int | None = None, number_of_replicas: int | None = None, bucket_capabilities: list[str] | None = None, storage_backend: str | None = None, server_groups: dict[str, Any] | None = None)

A description of a bucket and where its data is, from BucketManager.bucket_describe().

name

The name of the bucket.

Type:

str | None

uuid

The bucket’s UUID, which changes when a bucket is dropped and created again.

Type:

str | None

number_of_nodes

The number of nodes the bucket’s data is on.

Type:

int | None

number_of_replicas

The number of replicas the bucket keeps of each document.

Type:

int | None

bucket_capabilities

The capabilities the bucket supports.

Type:

list[str] | None

storage_backend

The storage engine the bucket keeps its data in.

Type:

str | None

server_groups

The server groups the bucket’s nodes are in.

Type:

dict[str, Any] | None

class couchbase.management.buckets.BucketManager(impl: BucketMgmtInterface)

Performs management operations on a cluster’s buckets.

bucket_describe(bucket_name: str, options: BucketDescribeOptions | None = None, **kwargs: Unpack[BucketDescribeOptionsKwargs]) → BucketDescribeResult

Provides details on provided the bucket.

Parameters:
  • bucket_name (str) – The name of the bucket to describe.

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

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Returns:

Key-value pair details describing the bucket.

Return type:

BucketDescribeResult

Raises:

BucketDoesNotExistException – If the bucket does not exist.

create_bucket(settings: CreateBucketSettings, options: CreateBucketOptions | None = None, **kwargs: Unpack[CreateBucketOptionsKwargs]) → None

Creates a new bucket.

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

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

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Raises:
drop_bucket(bucket_name: str, options: DropBucketOptions | None = None, **kwargs: Unpack[DropBucketOptionsKwargs]) → None

Drops an existing bucket.

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

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

  • **kwargs – keyword arguments that can be used as optional parameters for this operation.

Raises:

BucketDoesNotExistException – If the bucket does not exist.

flush_bucket(bucket_name: str, options: FlushBucketOptions | None = None, **kwargs: Unpack[FlushBucketOptionsKwargs]) → 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 – keyword arguments that can be used as optional parameters for this operation.

Raises:
get_all_buckets(options: GetAllBucketOptions | None = None, **kwargs: Unpack[GetAllBucketOptionsKwargs]) → list[BucketSettings]

Returns a list of existing buckets in the cluster.

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

  • **kwargs – 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: str, options: GetBucketOptions | None = None, **kwargs: Unpack[GetBucketOptionsKwargs]) → 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 – 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: BucketSettings, options: UpdateBucketOptions | None = None, **kwargs: Unpack[UpdateBucketOptionsKwargs]) → 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 – keyword arguments that can be used as optional parameters for this operation.

Raises:

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

class couchbase.management.buckets.BucketSettings(**kwargs: Unpack[BucketSettingsKwargs])

The settings of an existing bucket.

BucketManager.get_bucket() returns them and BucketManager.update_bucket() takes them. The settings are a dict, and a setting given as None is left out of it, so each property reads one key, or None if it is absent.

Raises:

InvalidArgumentException – If name is missing or empty.

property bucket_type: BucketType | None

The type of the bucket.

property compression_mode: CompressionMode | None

How the bucket compresses the documents it holds.

property conflict_resolution_type: ConflictResolutionType | None

How the bucket resolves a conflict between two versions of a document under XDCR.

It is fixed when the bucket is created, so it is sent to the server only from a CreateBucketSettings; BucketManager.update_bucket() never sends it.

property eviction_policy: EvictionPolicyType | None

How the bucket removes data from memory when it reaches its RAM quota.

property flush_enabled: bool | None

Whether the bucket can be flushed.

property history_retention_bytes: int | None

The largest the change history on disk can grow, in bytes, across all the bucket’s collections.

property history_retention_collection_default: bool | None

Whether the bucket’s collections keep a change history unless a collection is set otherwise.

property history_retention_duration: timedelta | None

The longest span of time the change history on disk covers, across all the bucket’s collections.

property max_expiry: timedelta | float | int | None

The longest expiry a document in the bucket can have, which a document written without one is given.

property max_ttl: timedelta | float | int | None

The longest expiry a document in the bucket can have, which a document written without one is given.

Deprecated since version 4.0.0: Use max_expiry instead.

property minimum_durability_level: DurabilityLevel | None

The durability level the bucket applies to a mutation that asks for a lower one.

property name: str

The name of the bucket.

property num_replicas: int | None

The number of replicas the bucket keeps of each document.

property num_vbuckets: int | None

The number of vBuckets the bucket is split into.

property ram_quota_mb: int | None

The bucket’s RAM quota on each node, in megabytes.

property replica_index: bool | None

Whether the bucket’s view indexes are replicated.

property storage_backend: StorageBackend | None

The storage engine the bucket keeps its data in.

class couchbase.management.buckets.BucketType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

The type of a bucket.

COUCHBASE keeps its data in memory and on disk, EPHEMERAL only in memory, and MEMCACHED is a memory-only cache.

COUCHBASE = 'membase'
EPHEMERAL = 'ephemeral'
MEMCACHED = 'memcached'
UNKNOWN = 'unknown'
class couchbase.management.buckets.CompressionMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

How a bucket compresses the documents it holds.

OFF stores documents as they arrive. PASSIVE keeps a document compressed when a client sends it compressed, and ACTIVE also compresses documents itself.

ACTIVE = 'active'
OFF = 'off'
PASSIVE = 'passive'
UNKNOWN = 'unknown'
class couchbase.management.buckets.ConflictResolutionType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

How a bucket resolves a conflict between two versions of a document under XDCR.

TIMESTAMP keeps the version written last, SEQUENCE_NUMBER the version changed most often, and CUSTOM leaves the conflict to the application.

CUSTOM = 'custom'
SEQUENCE_NUMBER = 'seqno'
TIMESTAMP = 'lww'
UNKNOWN = 'unknown'
class couchbase.management.buckets.CreateBucketSettings(**kwargs: Unpack[CreateBucketSettingsKwargs])

The settings of a bucket for BucketManager.create_bucket() to create.

They are BucketSettings that can also set conflict_resolution_type, which is fixed once the bucket exists.

class couchbase.management.buckets.EjectionMethod(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

How a Couchbase bucket removes data from memory: the whole document, or only its value.

FULL_EVICTION = 'fullEviction'
VALUE_ONLY = 'valueOnly'
class couchbase.management.buckets.EvictionPolicyType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

How a bucket removes data from memory when it reaches its RAM quota.

FULL and VALUE_ONLY apply to a Couchbase bucket, which keeps its data on disk: FULL removes a whole document, while VALUE_ONLY keeps its key and metadata in memory. NOT_RECENTLY_USED and NO_EVICTION apply to an ephemeral bucket, which has nowhere else to keep it: NOT_RECENTLY_USED removes the documents least recently used, while NO_EVICTION refuses new writes instead.

FULL = 'fullEviction'
NOT_RECENTLY_USED = 'nruEviction'
NO_EVICTION = 'noEviction'
UNKNOWN = 'unknown'
VALUE_ONLY = 'valueOnly'
class couchbase.management.buckets.StorageBackend(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

The storage engine a bucket keeps its data in.

COUCHSTORE = 'couchstore'
MAGMA = 'magma'
UNDEFINED = 'undefined'