A newer version of this documentation is available.

View Latest

Create a New Bucket

Full Administrators and Cluster Administrators can use the Couchbase Web Console, CLI, or REST API to create a new bucket.

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.

Bucket Settings

The 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 Tunable Memory with Ejection Policy before changing this setting.

bucket full ejection

Access Control

Access Control is configured using the Couchbase Web Console and is set for two ports: Standard port and Dedicated port:

admin access control

More details about standard and dedicated ports are provided in Authentication for Applications.

Conflict Resolution

The conflict resolution strategy is set on a per bucket basis. It is chosen during bucket creation and cannot be changed. The default conflict resolution setting is 'Sequence number'.

You can learn more about the two different conflict resolution strategies in XDCR Conflict Resolution. If you wish to enable the timestamp-based conflict resolution for your existing bucket while upgrading to version 4.6.0, then you must migrate your data to version 4.6.0. For instructions, see Migrating Data for the Timestamp-based Conflict Resolution.

You can also set the conflict resolution method using the CLI bucket-create command, or the REST API.

bucket create conflict resolution setting


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.

create 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


This setting enables or disables the flush operation for the bucket and is disabled (unchecked) by default. Checking this option does not directly trigger the flush, it only allows a flush to be triggered.

It is recommended that the flush capability is disabled in production as it irreversibly deletes every document in the bucket. Even for use cases where this is the desired behaviour, flushing is not recommended as it is a very disruptive process.

bucket flush

You can flush a bucket using the UI or using 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.

Create a New Bucket with CLI or REST API

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