A newer version of this documentation is available.

View Latest


Buckets are logical groups of items (keys and values) which can be used to organize, manage, and analyze the group of items.

Bucket types

There are two types of buckets:

  • Couchbase buckets use vBuckets to organize disk and memory storage on the nodes and distribution of items across the cluster. Items in a Couchbase bucket can be indexed through Views and Indexes created on the data in the buckets. These items can also be replicated between nodes and clusters using Database Change Protocol (DCP) and Cross Datacenter Replication (XDCR).

  • Memcached buckets exhibit special behavior.

Table 1. Bucket types in Couchbase Server
Bucket type Description


  • Provides highly-available and dynamically reconfigurable distributed data storage, with persistence and replication services.

  • 100% protocol compatible with, and built in the spirit of, the memcached open source distributed key-value cache.


  • Provides a directly-addressed, distributed (scale-out), in-memory, key-value cache.

  • Designed to be used alongside other database platforms such as relational database technology.

  • By caching frequently-used data, they reduce the number of queries a database server must perform for web servers delivering a web application.

With memcached buckets, the server provides only in-RAM storage and data does not persist on disk. If Couchbase Server runs out of space in the bucket’s RAM quota, it uses the Least Recently Used (LRU) algorithm to evict items from the RAM. This means the server removes the key, metadata, and all other data for the item from the RAM. Once evicted, you cannot retrieve the item.

The different bucket types support different capabilities.

Table 2. Bucket types and supported capabilities
Capability Memcached buckets Couchbase buckets

Item size limit

1 MB

20 MB











Limited set for in-memory statistics

Full suite

Client support

Ketama consistent hashing

Full smart client support










Encrypted data access



Couchbase buckets provide a highly-available and dynamically reconfigurable distributed data store. They survive node failures and allow cluster reconfiguration while continuing to service requests.

Table 3. Coucbase bucket capabilities
Couchbase bucket capability Description


Couchbase buckets operate through RAM. The data is stored in RAM and persisted to disk. The data is cached in RAM until the configured RAM is exhausted and data is ejected from the RAM. If the requested data is not currently in the cache (RAM), it will be loaded automatically from disk.


Couchbase server persists data objects asynchronously from memory to hard disk. This provides protection from server restarts. You can set persistence properties at the bucket level.


You can configure the number of replica servers that receive copies of all data objects. 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.


Rebalancing enables load distribution across resources and dynamic addition or removal of buckets and servers in the cluster.

Bucket authentication

Both Memcached and Couchbase buckets allow anonymous access and support SASL authentication.

  • SASL buckets: You can access SASL authenticating Couchbase buckets through port 11210. Each bucket is identified by its name and password, and you can use vBucket aware smart clients (SDKs) to access a SASL bucket. You cannot use legacy ASCII clients to reach these buckets.

  • Non-SASL buckets: You can place non-SASL buckets on any available port except port 11211, which is reserved for the default bucket. Port numbers are unique and help identify the buckets. Hence, you can place only one non-SASL bucket on any individual port. You can access non-SASL buckets using vBucket aware smart client (SDKs), as ASCII client or a binary client that does not use SASL authentication.

Smart clients discover changes in the cluster using the Couchbase Management REST API. Using SASL buckets you can isolate individual applications to provide multi-tenancy, or isolate data types in the cache to enhance performance and visibility. Using the Couchbase Server, you can configure different ports to access one of the following:

  • non-SASL buckets

  • isolated buckets using the binary protocol with SASL authentication, or

  • isolated buckets using the ASCII protocol with no authentication

You can use a mix of bucket types (Couchbase and memcached) in your environment. Buckets of different types share the same resource pool and cluster resources.

You can configure the quotas for RAM and disk usage per bucket, enabling you to manage resource usage across the cluster. As an administrator, you can modify quotas on a running cluster and re-allocate resources when usage patterns or priorities change.

The default bucket

The default bucket is a special bucket in Couchbase Server. When you first install Couchbase Server, the default bucket is automatically set up during installation. The default bucket is a non-SASL authenticating bucket that always resides on port 11211. You can remove the default bucket after installation and re-add it at a later time. When re-adding the default bucket, ensure that you place it on port 11211 and it must be a non-SASL authenticating bucket. You can access the default bucket using vBucket aware smart client (SDKs), an ASCII client, or a binary client that does not use SASL authentication.