Chapter 1. Introduction to Couchbase Server

Couchbase Server is a distributed, document-based database that is part of the NoSQL database movement. Couchbase Server is a persistent database that leverages an integrated RAM caching layer, enabling it to support very fast create, store, update, and retrieval operations. Couchbase is built on three core principles: Simple, Fast, Elastic.


The core of Couchbase Server is very simple and straightforward, and from a client perspective, very easy to use. Couchbase Server is also very quick and easy to install and set up. In fact, you can generally set up a new Couchbase Server node within five minutes. Couchbase Server is also compatible with memcached; if your application already uses memcached, then you can store data in Couchbase.

Finally, Couchbase Server builds on the basic key/value or document storage structure of memcached. This makes it very simple to store and retrieve data. You do not have to define a data structure before you start storing, and there are no complicated queries or query languages required to retrieve the data back.


Couchbase Server is very fast. Because Couchbase Server tries to retain as much of your actively used data in memory at all times, the speed of accessing the data stored within the database is generally limited only by the network speed required to access the storage value.

The result is that Couchbase Server supports sub-millisecond response times and has been optimized for very high-concurrency data storage. The system is linearly scalable due to a “shared nothing” architecture. You can improve the overall performance of your cluster by adding more nodes.


The Couchbase Server cluster is designed to be easily expanded. To create a multiple node cluster, install the software on another machine and add it to the existing cluster. You don’t need to take either the cluster (or the clients and applications that are using it) down to perform this operation. The entire cluster stays running during the process. Extending the cluster also results in linear improvements in capacity, as well as disk and network throughput.

These features are designed to support web application development where the high-performance characteristics are required to support low-latency and high throughput applications. Couchbase Server achieves this on a single server and provides support for the load to be increased almost linearly by making use of the clustered functionality built into Couchbase Server.

The cluster component distributes data over multiple servers to share the data and I/O load, while incorporating intelligence into the server and client access libraries that enable clients to quickly access the right node within the cluster for the information required. This intelligent distribution allows Couchbase Server to provide excellent scalability that can be extended simply by adding more servers as your load and application requirements increase.

Let’s take a closer look at the key components that make up Couchbase Server and how they work together to provide an efficient database environment.

Architecture and Concepts

In order to understand the structure and layout of Couchbase Server, you first need to understand the different components and systems that make up both an individual Couchbase Server instance, and the components and systems that work together to make up the Couchbase Cluster as a whole.

The following section provides key information and concepts that you need to understand the fast and elastic nature of the Couchbase Server database, and how some of the components work together to support a highly available and high-performance database.

Nodes and Clusters

Couchbase Server can be used either in a standalone configuration, or in a cluster configuration where multiple Couchbase Servers are connected together to provide a single, distributed, data store.

Collectively, you can identify the components of a Couchbase system as:

Couchbase Server or node

A single instance of the Couchbase Server software running on a machine, whether a physical machine, virtual machine, EC2 instance, or other environment.

All instances of Couchbase Server are identical, provide the same functionality, interfaces and systems, and consist of the same components.


All nodes within Couchbase Server are created equally. There is no hierarchy or topology, and no single node is a ‘master’ of the rest of the cluster. Each node is responsible only for the data it stores and the requests made to it by clients.


A cluster is a collection of one or more instances of Couchbase Server that are configured as a logical cluster. All nodes within the cluster are identical and provide the same functionality and information. The entire cluster shares data across the individual nodes, with each node being responsible for only a portion of the entire data set.

Clusters operate in a completely horizontal fashion. To increase the size of a cluster, you add another node. There are no parent/child relationships or hierarchical structures involved. This means that Couchbase Server scales linearly, both in terms of increasing the storage capacity and the performance and scalability.

Cluster Manager

Every node within a Couchbase Server Cluster includes the Cluster Manager component. The Cluster Manager is responsible for the following within a cluster:

  • Cluster management

  • Node administration

  • Node monitoring

  • REST API for management

  • Statistics gathering and aggregation

  • Runtime logging

  • Multitenancy

  • Security for administrative and client access


Couchbase Server provides data management services using named buckets. These are isolated virtual containers for data. A bucket is a logical grouping of physical resources within a cluster of Couchbase Servers. They can be used by multiple client applications across a cluster. Buckets provide a secure mechanism for organizing, managing, and analyzing data storage resources.

Couchbase Server provides the two core types of buckets that can be created and managed, summarized in Table 1-1. Couchbase Server collects and reports on runtime statistics by bucket type.

Table 1-1. Bucket types

Bucket typeDescription
CouchbaseProvides highly available and dynamically reconfigurable distributed data storage, providing persistence to disk and replication services. Couchbase buckets are 100% protocol compatible with Memcached.
MemcachedProvides a directly addressed, distributed (scale-out), in-memory, document cache. Memcached buckets are designed to be used alongside relational database technology—caching 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 core capabilities (as shown in Table 1-2). Couchbase-type buckets provide a highly available and dynamically reconfigurable distributed data store. Couchbase-type buckets survive node failures and allow cluster reconfiguration while continuing to service requests.

Table 1-2. Couchbase bucket capabilities

PersistenceData objects are persisted asynchronously to hard disks from memory to provide protection from server restarts or minor failures. Persistence properties are set at the bucket level.
ReplicationA configurable number of replicas can receive copies of all data objects in the Couchbase-type bucket. Every node within a cluster is responsible for both active and replica data. If a node fails, the replica can be promoted to be the active container, providing continuous (HA) cluster operations via failover. Replication operates at the bucket level with replicas distributed over multiple servers in the same way as the bucket data.
RebalancingRebalancing enables load distribution across resources and dynamic addition or removal of buckets and servers in the cluster.
Bucket sizingCouchbase buckets can be sized dynamically, allowing you to change and alter the bucket size as your application needs change.

Buckets can be used to isolate individual applications to provide multitenancy, or to isolate data types to enhance performance and visibility. Couchbase Server allows you to configure different ports to access different buckets. Password authentication is also available on individual buckets.


Smart clients discover changes in the cluster structure automatically by using the Couchbase Management REST API. This ensures that the client application continues to communicate to the appropriate node for the data being accessed.

Couchbase Server allows you to use and mix different types of buckets (Couchbase and Memcached) as appropriate in your environment. 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 so that administrators can reallocate resources as usage patterns or priorities change over time.


A vBucket is defined as the owner of a subset of the key space of a Couchbase cluster. These vBuckets are used to allow information to be distributed effectively across the cluster. The vBucket system is used both for distributing data, and for supporting replicas (copies of bucket data) on more than one node.

Clients access the information stored in a bucket by communicating directly with the node response for the corresponding vBucket. This direct access enables clients to communicate with the node storing the data, rather than using a proxy or redistribution architecture. The result is abstracting the physical topology from the logical partitioning of data. This architecture is what gives Couchbase Server elasticity.

This architecture differs from the method used by memcached, which uses client-side key hashes to determine the server from a defined list. This requires active management of the list of servers, and specific hashing algorithms such as Ketama to cope with changes to the topology. The structure is also more flexible and able to cope with changes than the typical sharding arrangement used in an RDBMS environment.


vBuckets are not a user-accessible component, but they are a critical component of Couchbase Server and are vital to the availability support and the elastic nature.

Every document ID belongs to a vBucket. A mapping function is used to calculate the vBucket in which a given document belongs. In Couchbase Server, that mapping function is a hashing function that takes a document ID as input and outputs a vBucket identifier. Once the vBucket identifier has been computed, a table is consulted to look up the server that “hosts” that vBucket. The table contains one row per vBucket, pairing the vBucket to its hosting server. A server appearing in this table can be (and usually is) responsible for multiple vBuckets.

Data in RAM

The architecture of Couchbase Server includes a built-in caching layer. This approach allows for very fast response times, since the data is initially written to RAM by the client, and can be returned from RAM to the client when the data is requested.

The effect of this design to provide an extensive built-in caching layer that acts as a central part of the operation of the system. The client interface works through the RAM-based data store, with information stored by the clients written into RAM and data retrieved by the clients returned from RAM; or loaded from disk into RAM before being returned to the client.

This process of storing and retrieving stored data through the RAM interface ensures the best performance. For the highest performance, you should allocate the maximum amount of RAM on each of your nodes. The aggregated RAM is used across the cluster.

This is different in design from other database systems where the information is written to the database and either a separate caching layer is employed, or the caching provided by the operating system is used to keep regularly used information in memory and accessible.


Ejection is a mechanism used with Couchbase buckets, and is the process of removing data from RAM to make room for active and more frequently used information—a key part of the caching mechanism. Ejection is automatic and operates in conjunction with the disk persistence system to ensure that data in RAM has been persisted to disk and can be safely ejected from the system.

The system ensures that the data stored in RAM will already have been written to disk, so that it can be loaded back into RAM if the data is requested by a client. Ejection is a key part of keeping frequently used information in RAM and ensuring that there is space within the Couchbase RAM allocation to load that data back into RAM when the information is requested by a client.


For Couchbase buckets, data is never deleted from the system unless a client explicitly deletes the document from the database or the expiration value for the document is reached. Instead, the ejection mechanism removes it from RAM, keeping a copy of that information on disk.


Each document stored in the database has an optional expiration value. The default is for there to be no expiration (i.e., the information will be stored indefinitely). The expiration can be used for data with a naturally limited life that you want to be automatically deleted from the entire database.

The expiration value is user-specified on a document basis at the point when the data is stored. The expiration can also be updated when the data is updated, or explicitly changed through the Couchbase protocol. The expiration time can either be specified as a relative time (for example, in 60 seconds), or absolute time (31st December 2012, 12:00 p.m.).

Typical uses for an expiration value include web session data, where you want the actively stored information to be removed from the system if the user activity has stopped and not been explicitly deleted. The data will time out and be removed from the system, freeing up RAM and disk for more active data.


Eviction is the process of removing information entirely from memory for Memcached buckets. The Memcached system uses a least recently used (LRU) algorithm to remove data from the system entirely when it is no longer used.


Within a Memcached bucket, LRU data is removed to make way for new data, with the information being deleted, since there is no persistence for Memcached buckets.

Disk Storage

For performance, Couchbase Server prefers to store and provide information to clients using RAM. However, this is not always possible or desirable in an application. Instead, what is required is the “working set” of information stored in RAM and immediately available for supporting low-latency responses.

Couchbase Server stores data on disk, in addition to keeping as much data as possible in RAM (as part of the caching layer used to improve performance). Disk persistence allows for easier backup/restore operations, and allows datasets to grow larger than the built-in caching layer.

Couchbase automatically moves data between RAM and disk (asynchronously in the background) in order to keep regularly used information in memory, and less frequently used data on disk. Couchbase constantly monitors the information accessed by clients, keeping the active data within the caching layer.

The process of removing data from the caching to make way for the actively used information is called ejection, and is controlled automatically through thresholds set on each configured bucket in your Couchbase Server Cluster.

The use of disk storage presents an issue in that a client request for an individual document ID must know whether the information exists or not. Couchbase Server achieves this using metadata structures. The metadata holds information about each document stored in the database, and this information is held in RAM. This means that the server can always return a “document ID not found” response for an invalid document ID, while returning the data for an item either in RAM (in which case it is returned immediately), or after the item has been read from disk (after a delay, or until a timeout has been reached).

The process of moving information to disk is asynchronous. Data is ejected to disk from memory in the background while the server continues to service active requests. During sequences of high writes to the database, clients will be notified that the server is temporarily out of memory until enough items have been ejected from memory to disk.

Similarly, when the server identifies an item that needs to be loaded from disk because it is not in active memory, the process is handled by a background process that processes the load queue and reads the information back from disk and into memory. The client is made to wait until the data has been loaded back into memory before the information is returned.

The asynchronous nature and use of queues in this way enables reads and writes to be handled at a very fast rate, while removing the typical load and performance spikes that would otherwise cause a traditional RDBMS to produce erratic performance.


When Couchbase Server is restarted or when it is started after a restore from backup, the server goes through a warm-up process. The warm-up loads data from disk into RAM, making the data available to clients.

The warmup process must complete before clients can be serviced. Depending on the size and configuration of your system, and the amount of data that you have stored, the warmup may take some time to load all of the stored data into memory.


The way data is stored within Couchbase Server is through the distribution offered by the vBucket structure. If you want to expand or shrink your Couchbase Server cluster, then the information stored in the vBuckets needs to be redistributed between the available nodes, with the corresponding vBucket map updated to reflect the new structure. This process is called rebalancing.

Rebalancing is an deliberate process that you need to initiate manually when the structure of your cluster changes. The rebalance process changes the allocation of the vBuckets used to store the information, and then physically moves the data between the nodes to match the new structure.

The rebalancing process can take place while the cluster is running and servicing requests. Clients using the cluster read and write to the existing structure, with the data being moved in the background between nodes. Once the moving process is complete, the vBucket map is updated and communicated to the smart clients and the proxy service (Moxi).

The result is that the distribution of data across the cluster has been rebalanced (or smoothed out) so that the data is evenly distributed across the database, taking into account the data and replicas of the data required to support the system.

Replicas and Replication

In addition to distributing information across the cluster for the purposes of even data distribution and performance, Couchbase Server also includes the ability to create additional replicas of the data. These replicas work in tandem with the vBucket structure, with replicas of individual vBuckets distributed data around the cluster. Distribution of replicas is handled in the same way as the core data, with portions of the data distributed around the cluster to prevent a single point of failure.

The replication of this data around this cluster is entirely peer-to-peer based, with the information being exchanged directly between nodes in the cluster. There is no topology, hierarchy, or master/slave relationship. When the data is written to a node within the cluster, the data is stored directly in the vBucket and then distributed to one or more replica vBuckets simultaneously using the TAP system.

In the event of a failure of one of the nodes in the system, the replica vBuckets are enabled in place of the vBuckets that were failed in the bad node. The process is near-instantaneous. Because the replicas are populated at the same time as the original data, there is no need for the data to be copied over; the replica vBuckets are there waiting to be enabled with the data already within them. The replica buckets are enabled and the vBucket structure updated so that clients now communicate with the updated vBucket structure.

Replicas are configured on each bucket. You can configure different buckets to contain different numbers of replicas according to the required safety level for your data. Replicas are only enabled once the number of nodes within your cluster support the required number of replicas. For example, if you configure three replicas on a bucket, the replicas will only be enabled once you have four nodes.


The number of replicas for a bucket cannot be changed after the bucket has been created.


Information is distributed around a cluster using a series of replicas. For Couchbase buckets you can configure the number of replicas (complete copies of the data stored in the bucket) that should be kept within the Couchbase Server Cluster.

In the event of a failure in a server (either due to transient failure, or for administrative purposes), you can use a technique called failover to indicate that a node within the Couchbase Cluster is no longer available, and that the replica vBuckets for the server are enabled.

The failover process contacts each server that was acting as a replica and updates the internal table that maps client requests for documents to an available server.

Failover can be performed manually, or you can use the built-in automatic failover that reacts after a preset time when a node within the cluster becomes unavailable.

For more information, see Failover with Couchbase.


The TAP protocol is an internal part of the Couchbase Server system and is used in a number of different areas to exchange data throughout the system. TAP provides a stream of data of the changes that are occurring within the system.

TAP is used during replication, to copy data between vBuckets used for replicas. It is also used during the rebalance procedure to move data between vBuckets and redestribute the information across the system.

Client Interface

There are a number of client libraries available, and clients fall into two major categories, those that are smart clients, and those that are memcached-compatible. Smart clients communicate with the cluster as a whole, and information is automatically written to the correct node within the cluster according to the built-in cluster configuration and distribution of information over the vBuckets. Smart clients also communicate with the cluster to ensure that during a failover or rebalancing event, the client updates the configuration and writes to the appropriate cluster.

When using a non-smart memcached-compatible client, you must use a client-side Moxi component. The Moxi tool acts as a proxy server between your client connection and the Couchbase Server cluster. It provides the cluster level distribution and interfacing, while allowing traditional memcached clients to write to the Couchbase Cluster. Using a client-side Moxi service also enables you to take advantage of Couchbase Server functionality without changing your existing memcached application in any way.


There are memcached clients available for a huge range of languages and environments. See

Within Couchbase Server, the techniques and systems used to get information into and out of the database differ according to the level and volume of data that you want to access. The different methods can be identified according to the base operations of Create, Retrieve, Update, and Delete:


Information is stored into the database using the Couchbase client interface to store a document against a specified document ID. Bulk operations for setting the documents of a larger number of operations at the same time are available, and these are more efficient than multiple smaller requests.


For basic store/retrieve operations, Couchbase Server is compatible with the memcached client protocol. For the more advanced operations, you will need to use one of the Couchbase client libraries.

The value stored can be any binary value, including structured and structured strings, serialized objects (from the native client language), or native binary data (for example, images or audio).


To retrieve, you must know the document ID used to store a particular value. You can also perform bulk operations to get multiple documents with the same operation, which is more efficient than multiple single requests.


Updates operations include operations to update the entire document, and also to perform simple operations, such as appending or prepending information to the existing record, or incrementing and decrementing integer values.


There is a single delete operation to remove a document entirely from the database.

Smart clients are available for the following languages and environments directly from Couchbase:

At the time of writing, there is also an experimental Python client available, ( Mark Nunberg has also written a Perl client, Couchbase::Client, which is based on the libcouchbase library for C. You can get more information from

Proxy (Moxi)

Couchbase Server includes a component called Moxi. Moxi provides a proxying service to allow traditional memcached clients to use Couchbase Server without making changes to your application or having to modify your environment to use a smart client library.

The proxy service provides connection pooling for clients and responds to topology updates within the Couchbase Server cluster to ensure that information is distributed across the cluster correctly.

If you are using one of the Couchbase clients, then you do not need to use Moxi.


Moxi can be used in either a server-side or client-side environment. Server-side deployments involve an additional network hop, and the load and redirection of information can create problems within a production environment.

A client-side deployment, where the Moxi service is installed on each client node, is the recommended solution for production deployments.

Administration Tools

Couchbase Server was designed to be as easy to use as possible, and does not require constant attention, except for the monitoring of health status and capacity. Administration is, however, offered in a number of different tools and systems.

Couchbase Server includes three solutions for managing and monitoring your Couchbase Server and cluster:

Web administration console

Couchbase Server includes a built-in web-administration console that provides a complete interface for configuring, managing, and monitoring your Couchbase Server installation.

Command line interface

Couchbase Server includes a suite of command-line tools that provide information and control over your Couchbase Server and cluster installation. These can be used in combination with your own scripts and management procedures to provide additional functionality, such as automated failover, backups, and other procedures.

Administration REST API

Both the Web Administration Console and the command-line interfaces make use of a built-in REST API that provides the full suite of management functionality. All of the management functionality is exposed through the REST API, and as such, it acts as the authoritative interface to the server.

Because the REST interface is so complete, you can use it from your own custom management and administration scripts to support different operations.

Statistics and Monitoring

In order to understand what your cluster is doing and how it is performing, Couchbase Server incorporates a complete set of statistical and monitoring information. The statistics are provided through all of the administration interfaces.

The level of detail provided by the statistics is considerable. There is complete transparency within the system to monitor all aspects of the performance and operation of the system, allowing you to monitor and pinpoint very specific elements of your system. The structure is also granular in nature, allowing you to look at different levels of detail into different aspects of the system.

The key statistics required to monitor the health of your system are exposed through the Web Administration Console. These statistics are provided using built-in real-time graphing, allowing you to monitor the health and performance of your system.

Get Getting Started with Couchbase Server now with the O’Reilly learning platform.

O’Reilly members experience live online training, plus books, videos, and digital content from nearly 200 publishers.