Buckets

Buckets

Couchbase Server uses buckets to group collections of keys and values logically. A Couchbase cluster can have multiple buckets, each with its own memory quota, number of replica copies, and capabilities. Couchbase Server supports three different types of bucket, the properties of which are described in this section.

Bucket Types

Three types of bucket are provided:

  • Couchbase buckets: These allow data to be automatically replicated for high availability, using the Database Change Protocol (DCP); and dynamically scaled across multiple servers, by means of Cross Datacenter Replication (XDCR).

    If a Couchbase bucket's RAM-quota is exceeded, items are ejected. This means that data, which is resident both in memory and on disk, is removed from memory, but not from disk. Therefore, if removed data is subsequently needed, it is reloaded into memory from disk. For a Couchbase bucket, ejection can be either of the following, based on configuration performed at the time of bucket-creation:
    • Value-only: Only key-values are removed. Generally, this favors performance at the expense of memory.

    • Full: All data — including keys, key-values, and meta-data — is removed. Generally, this favors memory at the expense of performance.
  • Ephemeral buckets: These are an alternative to Couchbase buckets, to be used whenever persistence is not required: for example, when repeated disk-access involves too much overhead. This allows highly consistent in-memory performance, without disk-based fluctuations. It also allows faster node rebalances and restarts.

    If an Ephemeral bucket's RAM-quota is exceeded, one of the following occurs, based on configuration performed at the time of bucket-creation:

    • Resident data-items remain in RAM. No additional data can be added; and attempts to add data therefore fail.

    • Resident data-items are ejected from RAM, to make way for new data. For an Ephemeral bucket, this means that data, which is resident in memory (but, due to this type of bucket, can never be on disk), is removed from memory. Therefore, if removed data is subsequently needed, it cannot be re-acquired from Couchbase Server.

      For an Ephemeral bucket, ejection removes all of an item's data: however, a tombstone (a record of the ejected item, which includes keys and metadata) is retained until the next scheduled purge of metadata for the current node. See Bucket Disk Storage for more information.

  • Memcached buckets: These are designed to be used alongside other database platforms, such as ones employing relational database technology. By caching frequently-used data, Memcached buckets reduce the number of queries a database-server must perform. Each Memcached bucket provides a directly addressable, distributed, in-memory key-value cache.

    Memcached buckets are not persistent on disk: they only exist in RAM. If a Memcached bucket's RAM-quota is exceeded, items are ejected. For a Memcached bucket, this means that data, which is resident in memory (but, due to this type of bucket, can never be on disk), is removed from memory. Therefore, if removed data is subsequently needed, it cannot be re-acquired from Couchbase Server. Ejection removes all of an item's data.

For all bucket-types, items are selected for ejection by means of the Not Recently Used (NRU) algorithm.

All bucket types are fully compatible with the Memcached open source distributed key-value cache.

Bucket Capabilities

Each bucket type supports a different set of capabilities; as shown by the following table.

Table 1. Bucket types and associated capabilities
Capability Memcached buckets Couchbase buckets Ephemeral buckets
Item size limit 1 MB 20 MB 20 MB
Persistence No Yes No
Replication (DCP) No Yes Yes
Cross Datacenter Replication (XDCR) No Yes Yes
Rebalance No Yes Yes
Statistics All except disk-related All All except disk-related
Client support Ketama consistent hashing Full smart client support Full smart client support
Backup No Yes Yes
Querying via N1QL No Yes Yes
Map-reduce & spatial views No Yes No
Global Secondary Indexes No Yes No
Memory Optimized Indexes No Yes Yes
Full-Text Search No Yes Yes
External connectors No Yes Yes
Encrypted data access Yes Yes Yes
Durability: Persist To No Yes No
Durability: Replication No Yes Yes
TTL Yes Yes Yes

Couchbase vs Ephemeral Buckets

Couchbase and Ephemeral buckets both provide a highly available, dynamically reconfigurable, distributed data-store; which survives node failures, and allows cluster-reconfiguration to occur while service-requests continue to be handled. The following table compares the principal capabilities shared by both bucket-types.

Table 2. Couchbase and Ephemeral bucket-capabilities compared
Capability Couchbase Buckets Ephemeral Buckets
Persistence Couchbase buckets are persisted asynchronously, from memory to disk. This provides protection from server-restarts. You can set persistence-properties at the bucket level. Ephemeral buckets are not persisted to disk: they are retained in RAM only.
Replication (DCP and XDCR) Couchbase buckets can be replicated across a configurable number of servers. If the host machine fails, a replica server is promoted to be the host server, providing high availability cluster operations via failover. You can configure replication at the bucket level. Additionally, Cross Datacenter Replication (XDCR) allows replication of Couchbase bucket-data between clusters. Ephemeral buckets can be replicated across a configurable number of servers, exactly as can Couchbase buckets; but without being persisted to disk. Likewise, XDCR allows replication of Ephemeral bucket-data between clusters and without persistence: note however, that an Ephemeral bucket configured to eject data when its RAM-quota is exceeded is not permitted to be used as a source for XDCR (though it is permitted to be used as a target).
Rebalance By means of rebalancing, the load constituted by Couchbase buckets is distributed evenly across nodes within the cluster. Buckets and nodes can be dynamically added and removed. Rebalancing redistributes Ephemeral buckets, exactly as it does Couchbase buckets; but without the data being persisted to disk.
Auto-failover By default, Auto-failover starts when a node has been inaccessible for 120 seconds. Auto-failover can happen only once, for a single node; prior to manual reset, performed by an administrator. When a failed node becomes accessible again, delta-node recovery is used: re-using data on disk, and resynchronizing it. Auto-failover starts as soon as a node is inaccessible. Auto-failover can happen multiple times, for multiple nodes. When a failed node becomes accessible again, no delta-node recovery is required, since no data resides on disk.

Bucket Security

Buckets are protected by the Couchbase Role-Based Access Control (RBAC) system. See Authorization and Authentication for details.

Legacy buckets, defined on releases of Couchbase Server prior to 5.0, may continue to be accessible without password-specification. However, you are strongly recommended to ensure that all buckets are fully protected by RBAC, especially for production purposes.

Using Buckets in Administration and Development

For information on how to create, access, and manage buckets, see Setting Up Buckets.