A newer version of this documentation is available.

View Latest

Create a new bucket

You can either use the Couchbase Web Console, CLI, or REST API to create a new bucket.

To create a new bucket using the Couchbase Web Console, go to Data Buckets  Create New Data Bucket.

A dialog containing the configuration for your new bucket appears. Remember that when you create a new bucket and save the configuration, the node status indicator will be yellow until all of the vBuckets are created across the cluster. Once this is finished, the indicator turns green.

You can also use the Couchbase Server CLI command bucket-create or REST API command rest-bucket-create.

Bucket settings

Your bucket name can only contain characters in range A-Z, a-z, 0-9 as well as underscore, period, dash and percent and can be a maximum of 100 characters in length.

There are two bucket types: Couchbase buckets and Memcached buckets. In most circumstances choose a Couchbase bucket, even if all you are using Couchbase Server only as a Highly Available Cache system.

If you need the memcached-like functionality, it is recommended that you use Couchbase’s memcached proxy Moxi. The memcached buckets are available to provide administration capabilities for regular memcached and backward compatibility and offer none of the high-end features Couchbase Server is known for. For more specific information, see Buckets.

bucket new

Memory size

In the Memory Size section, you will configure the RAM quota your bucket will allocate on a per node basis. The value you enter must fit with the overall cluster RAM quota. The cluster quota and what you are trying to add are displayed in the bar on the Setting page. The bucket RAM quota can be dynamically altered up or down with zero downtime to the cluster at any point in the future, provided you have enough cluster resources.

Regarding Cache Metadata, keep in mind that it can have serious implications on your application’s performance.

Use Value ejection unless you know very well what Full ejection does, why you should use it and what impacts it can have on your application and the operation of your database. If you use Full ejection effectively, it is very powerful and expands what you can do with Couchbase Server. If you use it incorrectly, it can cause performance problems in your application and operation of your database. Please make sure you read the detailed documentation on Full ejection before changing this setting.

bucket full ejection


One replica is configured by default, even if your cluster does not yet have enough nodes to support replicas (minimum two nodes).

The general rule is to have a replica for each node that can fail in the cluster. Best practice is to keep at least one replica copy configured at all times and most users run with one replica. If you decide that more replica copies are needed for your bucket, make sure that you read the sizing section of Couchbase Server documentation. The more replicas you have, the more server and network resources are required.

In general, you will have one replica for clusters up to 5 data nodes, one or two replicas in clusters from 5 to 10 data nodes and three replicas only in clusters with 10 or more data nodes.

bucket replicas

Disk I/O Optimization

The Disk I/O setting control the disk I/O priority the bucket will get. The setting defaults to low priority, because if all buckets in a cluster are set to the same priority then all buckets get the same disk I/O.

This setting only enables prioritization if at least one bucket in the cluster is set differently. Therefore, there is no effect if all buckets are set to high priority. If buckets with different priorities exist in the cluster, there are internal server resources allocated for high and low priority buckets.

bucket disk io


This setting allows you to override the cluster-wide auto-compaction settings for the specified bucket.

For the most part, you should never need to use this setting.

bucket auto compact


The Flush option deletes every object in a bucket and is disabled (unchecked) by default.

It is used exclusively for one purpose: to enable your application to use the flush method and delete every object in the bucket.

Use the Flush option sparingly. It is highly recommended that you never run with this option enabled in production unless you absolutely must. It can be as dangerous as it sounds.

The Flush option flags the items for removal in a memcached bucket and immediately removes items in a Couchbase bucket.

Enable the Flush option either during the bucket creation phase or later, while changing the bucket settings. In both cases, after enabling this option you still must click on the red button Flush to proceed with flushing. Using this button is an additional security measure to prevent unintentional loss of data.

bucket flush

You can also use the commands the CLI command bucket-flush and REST API rest-bucket-flush.

Bucket creation status update

After the bucket creation is completed, you can get the status update as follows:

  • Send a GET or any other command to the memcached on the created bucket. If you receive the response ETMPFAIL, try the command later.

  • Monitor the ep-engine bucket stats on one of the nodes. The bucket is created when the stat ep_degraded_mode changes from true to false.

  • Monitor /pools/default/buckets/<bucketname> or /pools/default/bucketsStreaming/<bucketname>. The bucket is created when all node statuses turn from warmup to healthy.