Memory and Storage

To facilitate high-speed data-access, Couchbase Server provides a caching layer and tunable disk I/O priorities.

Caching and Persistence

Couchbase Server provides a fully integrated caching layer, which provides high-speed data-access. Couchbase Server automatically manages the caching layer, ensuring that sufficient memory is available in relation to occupied disk-space, in order to maintain optimal performance. Data associated with Couchbase (as opposed to Ephemeral) buckets is also maintained persistently, on disk. Such items, when they come into the caching layer, are placed on the disk queue, to be written to disk; and at the same time, if appropriate, are placed on a replication queue, so that one or more replica buckets can be created or updated.

Memory quotas, established by the Full Administrator when the server is configured, are automatically managed by Couchbase Server with reference to watermarks, which specify how much free memory should be consistently maintained within the caching layer. Consequently, infrequently used items are written to disk; and are then removed from memory in order to free up space. This process, referred to as ejection, is managed asynchronously, while the server continues to service active requests. Items ejected from Couchbase buckets can subsequently be re-acquired from disk, as necessary. A working-set of most frequently used data is tracked and maintained, and the items kept in memory to ensure high performance. The priority of disk I/O is configurable per bucket.

Saving New Items

When a new item, such as a document, is saved by an application, it is saved in memory only, if the item is contained by an Ephemeral bucket; and is saved both in memory and on disk, if the item is contained by a Couchbase bucket. If the bucket (either Ephemeral or Couchbase) has been replicated one or more times, a copy of the new item is saved in each replica.

The following sequence illustrates how a new document is created by an application and saved in a Couchbase bucket. It is assumed that the bucket has at least one replica on the cluster.

The application creates a new document.
The application saves the document on Couchbase Server. The document is received in memory.
Couchbase Server places a compressed copy of the document onto the Disk Queue so that the document can be written to the disk; and a further copy onto the Replication Queue, so that the document can be written to the replica bucket. (The copy placed on the Replication Queue may or may not be compressed, depending on the compression mode configured for the bucket.)
Once written, the new document resides both in the memory and on the disk of the node. It will also reside in the memory and on the disk of whichever other nodes maintain the replicas of its buckets.

On each node containing the bucket or a replica, the document remains in memory; unless it is ejected at some point, after which it remains on disk.

Updating Items

Items that reside in the memory of Couchbase Server can be updated. If the item belongs to a Couchbase bucket, the item is also updated on disk. If the item is not currently in memory, but resides on disk, Couchbase Server retrieves the item, so that it can be updated. This is demonstrated by the following sequence.

The application provides an update to an existing document.
Since the document is not currently in memory, Couchbase Server seeks it on disk, where is resides in compressed form.
The compressed document is retrieved, brought into memory, and decompressed.
The application’s updates are applied to the uncompressed document.
The updated document is placed (in either compressed or uncompressed form, as appropriate) on the replication queue, so that replicas can be updated. The updated document is also re-compressed, and written to disk locally.
The updated document is now retained locally on disk and in memory. The document remains in memory unless it is ejected at some point, after which it continues to reside on disk.