Data storage

Couchbase Server provides data management services using buckets, which are isolated virtual containers for data. A bucket is a logical grouping of physical resources within a cluster of Couchbase Servers.

Important: A newer version of this software with updated documentation is available. Visit the Couchbase Developer Portal for more information.

Buckets provide a secure mechanism for organizing, managing, and analyzing the data storage resources. Two types of data buckets, memcached and Couchbase, enable you to store data either in-memory only or both in-memory and on disk (for added reliability). Select the appropriate bucket type for your implementation during the Couchbase Server setup.

Note: Buckets can be used by multiple client applications across a cluster.
Bucket Type Description
Couchbase Provides highly-available and dynamically reconfigurable distributed data storage, with persistence and replication services. Couchbase buckets are 100% protocol compatible with, and built in the spirit of, the memcached open source distributed key-value cache.
memcached Provides a directly-addressed, distributed (scale-out), in-memory, key-value cache. Memcached buckets are designed to be used alongside relational database technology. They cache frequently-used data, thereby reducing the number of queries a database server must perform for web servers delivering a web application.

The different bucket types support different capabilities.

Capability memcached buckets Couchbase buckets
Item size limit 1 MB 20 MB
Persistence No Yes
Replication No Yes
Rebalance No Yes
Statistics Limited set for in-memory stats Full suite
Client support memcached, should use Ketama consistent hashing Full Smart Client Support
XDCR No Yes
Backup No Yes
Tap/DCP No Yes
Encrypted data access No Yes

Couchbase-type buckets provide a highly-available and dynamically reconfigurable distributed data store, survive node failures, and allow cluster reconfiguration while continuing to service requests. They have the following core capabilities:

Couchbase bucket capability Description
Caching Couchbase buckets operate through RAM. Data is kept in RAM and persisted down to disk. Data will be cached in RAM until the configured RAM is exhausted, and data is ejected from RAM. If the requested data is not currently in the the RAM cache, it will be loaded automatically from disk.
Persistence Data objects can be persisted asynchronously to the hard-disk resources from memory to provide protection from server restarts or minor failures. Persistence properties are set at the bucket level.
Replication A configurable number of replica servers can receive copies of all data objects in the Couchbase-type bucket. If the host machine fails, a replica server can be promoted to be the host server, providing high availability cluster operations via failover. Replication is configured at the bucket level.
Rebalancing Rebalancing enables load distribution across resources and dynamic addition or removal of buckets and servers in the cluster.

Both the memcached and Couchbase buckets can be authenticated via SASL, or not authenticated (non-SASL).

The following bucket types can be configured:

Default bucket
The default bucket is a Couchbase bucket that always resides on port 11211 and is a non-SASL authenticating bucket. When Couchbase Server is first installed, this bucket is automatically set up during installation. It can be removed after the installation and can also be re-added later. If you decide to add the bucket named default at a later time, it must be placed on port 11211 and must be a non-SASL authenticating bucket. A bucket that is not named default cannot reside on port 11211 if it is a non-SASL bucket. The default bucket can be reached with a vBucket aware smart client, an ASCII client or a binary client that doesn’t use SASL authentication.
Non-SASL buckets
Non-SASL buckets can be placed on any available port, with the exception of port 11211 if the bucket is not named default. Only one Non-SASL bucket can be placed on any individual port. These buckets can be reached with a vBucket aware smart client, an ASCII client or a binary client that doesn’t use SASL authentication.
SASL buckets
SASL authenticating Couchbase buckets can only be placed on port 11211 and each bucket is differentiated by its name and password. A SASL bucket cannot be placed on any port other than 11211 and can be reached with either a vBucket aware smart client, or a binary client that has SASL support. These buckets cannot be reached with ASCII clients.

Smart clients discover changes in the cluster using the Couchbase Management REST API. The SASL buckets can be used to isolate individual applications to provide multi-tenancy, or to isolate data types in the cache to enhance performance and visibility. Couchbase Server allows you to configure different ports to access different buckets, and provides the option to access isolated buckets using either the binary protocol with SASL authentication or the ASCII protocol with no authentication.

Couchbase Server allows you to use and mix different types of buckets in your environment, Couchbase and memcached. Buckets of different types still share the same resource pool and cluster resources.

Quotas for RAM and disk usage are configurable per bucket, so that resource usage can be managed across the cluster. Quotas can be modified on a running cluster and administrators can re-allocate resources as usage patterns or priorities change over time.