Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Create a Bucket

  • how-to
    +
    Full, Cluster, and Backup Administrators can use Couchbase Web Console, the CLI, or the REST API to create a bucket.

    You can create a bucket using the following methods:

    You can create a maximum of 30 buckets per cluster.

    Prerequisites

    • You have the Full, Cluster, or Backup Administrator role.

    • Your cluster must have less than 30 buckets.

    Create a Bucket with the UI

    To create a bucket with the Couchbase UI:

    1. Log in to the Couchbase Server Web Console.

    2. Click Buckets.

    3. Click Add Bucket.

      The Add Data Bucket dialog appears:

    An image that displays the Add Data Bucket dialog. The Name field is empty. Bucket Type is set to Couchbase, and the Storage Backend is set to Magma with 128 vBuckets. The Memory Quota is set to 312MiB. The Advanced bucket settings is collapsed.

    1. In the Name field, enter a name for the new bucket. A bucket name can be up to 100 characters in length and contain:

      • Uppercase and lowercase characters (A-Z and a-z)

      • Digits (0-9)

      • Underscores (_), periods (.), dashes (-), and percent symbols (%)

    2. Choose a Bucket Type for the bucket:

      • Couchbase

      • Ephemeral

      For more information about bucket types, see Buckets.

    3. Choose a Storage Backend for the bucket:

      • Couchstore

      • Magma

      If you choose Magma, you can also choose the number of vBuckets for the bucket. For more information about the available storage engines, see Storage Engines.

    4. In the Memory Quota field, enter a value in MiB per node for the total RAM available for the bucket. This value cannot exceed the total RAM quota for your cluster. It must also be equal to or greater than the minimum memory quota required by your chosen storage engine:

      Storage Engine Minimum Memory Quota

      Couchstore

      100 MiB

      Magma (128 vBuckets)

      100 MiB

      Magma (1024 vBuckets)

      1 GiB

      Your setting should also meet or surpass the memory resident requirement of the storage backend for your anticipated dataset size. For example, Magma has a minimum memory-to-data ratio of 1% of the data size. Suppose you expect the dataset in your Magma bucket to be 5 TiB. Then set the memory quota to at least 51 GiB. For more information, see Bucket Memory Quotas.

    1. Expand Advanced bucket settings.

    2. Set any advanced settings for your bucket. See Set Advanced Bucket Settings.

    3. Select Add Bucket.

    The bucket appears on the Buckets screen.

    An image that displays the bucket list on the Buckets screen, and the search bar for filtering the available buckets. A single bucket, called testBucket, displays in the table. It has no items, and uses 27MiB out of the 256MiB RAM quota available. It uses 4.08MiB of disk space.

    You can view the following information for the bucket:

    • The number of items the bucket contains.

    • The percentage of items in the bucket that are currently resident.

    • The number of operations per second being performed on the bucket.

    • The amount of RAM the bucket is currently using, compared to its memory quota.

    • The amount of disk space used by the bucket.

    You can also view the Documents in the bucket and create Scopes and Collections.

    For information about how to import documents into a bucket, see Import Documents.

    Set Advanced Bucket Settings

    The available advanced settings for your bucket change based on your selected Bucket Type:

    Couchbase Bucket Advanced Settings

    The Couchbase Bucket advanced settings let you set options such as replication, compression, and flushing.

    An image that displays the Add Data Bucket dialog’s Advanced bucket settings with the default selections for a Couchbase bucket.

    To configure advanced settings for a Couchbase bucket:

    1. To enable replica creation and management, under Replicas, select the Enable checkbox.

      1. In the Number of replica (backup) copies list, select the number of replicas for the bucket. Note that if a required minimum for the configurable number of replicas has previously been established by an administrator, an attempt to specify a lower number produces the error message Replica number must be equal to or greater than x, where x is the minimum number of replicas. For information on establishing a minimum, see the REST API reference page, Setting a Replica-Minimum.

      2. To replicate view indexes and data from the bucket, select the Replicate view indexes checkbox.

    2. To set a document expiration for documents in the bucket, under Bucket Max Time-To-Live, select the Enable checkbox.

      1. In the Seconds field, enter the maximum time in seconds that a document can exist in the bucket before it’s deleted.

        The maximum allowed value is 2147483647 seconds (68.096 years). You can only apply this setting to documents created after you change the configuration.

    3. Choose a Compression Mode for the bucket:

      • Off

      • Passive

      • Active

      For more information about the available compression modes, see Compression.

    4. Choose a Conflict Resolution method for Cross Datacenter Replication (XDCR) on this bucket:

      • Sequence number

      • Timestamp

      For more information about XDCR conflict resolution, see XDCR Conflict Resolution.

    5. Choose an Ejection Method for the bucket:

      • Value-only

      • Full

      For more information about ejection, see the Ejection section in Memory.

    Use the Full Ejection policy for buckets using the Magma storage engine. This setting works well when the ratio of memory to data is low. In these cases, retaining just the keys and metadata of documents can still consume significant portions of the allocated memory. Magma allows you to set a memory to data ratio as low as 1%.

    1. In the Minimum Durability Level list, select a durability level for the bucket:

      • none

      • majority

      • majorityAndPersistActive

      • persistToMajority

      For more information about durability, see Durability.

    2. To enable automatic compaction of data and indexes to save space, select the Auto-Compaction checkbox.

      1. To override the default Auto-Compaction settings, select the Override the default auto-compaction settings? checkbox.

        For more information about how to configure Auto-Compaction, see Auto-Compaction.

    3. To enable flushing for the bucket, under Flush, select the Enable checkbox.

      For more information about flushing, see Flush a Bucket.

    An image that displays the Add Data Bucket dialog, with a Couchbase Bucket Type and CouchStore Storage Backend selected. The Advanced bucket settings are expanded and to show the default selections for a Couchbase and Couchstore bucket.
    Enable Cross Cluster Versioning can be enabled only in the Edit a Bucket mode. Enabling Cross Cluster Versioning is a prerequisite for features like XDCR Conflict Logging and XDCR Active-Active with Sync Gateway 4.0+. For more information, see XDCR enableCrossClusterVersioning.

    Ephemeral Bucket Settings

    An image that displays the Add Data Bucket dialog, with the Bucket Type set to Ephemeral and the Storage Backend set to CouchStore. The Advanced bucket settings are expanded to show the default selections for a Ephemeral and Couchstore bucket.

    To configure advanced settings for an Ephemeral bucket:

    1. To enable replica creation and management, under Replicas, select the Enable checkbox.

      1. In the Number of replica (backup) copies list, select the number of replicas for the bucket.

    2. To set a document expiration for documents in the bucket, under Bucket Max Time-To-Live, select the Enable checkbox.

      1. In the Seconds field, enter the maximum number of seconds a document can exist in the bucket before it’s deleted.

        The maximum allowed value is 2147483648 seconds (68.096 years). You can only apply this setting to documents created after you change the configuration.

    3. Choose a Compression Mode for the bucket:

      • Off

      • Passive

      • Active

      For more information about the available compression modes, see Compression.

    4. Choose a Conflict Resolution method for Cross Datacenter Replication (XDCR) on this bucket:

      • Sequence number

      • Timestamp

      For more information about XDCR conflict resolution, see XDCR Conflict Resolution.

    5. Choose an Ejection Policy for the bucket:

      • No ejection

      • Eject data when RAM is full

      For more information about ejection, see the Ejection section in Memory.

    6. In the Metadata Purge Interval field, enter a value between 0.0007-60 to set how often a node purges metadata on deleted items.

      A value of 0.0007 equals a minute. A value of 0.5 equals 12 hours. If this value is too high, the node might have a delay when reclaiming memory. If set too low, data might be inconsistent in XDCR or Views.

    7. In the Minimum Durability Level list, select a durability level for the bucket:

      • none

      • majority

      For more information about durability, see Durability.

    Create a Bucket with the CLI

    To create a bucket with the Couchbase command-line tool, use the bucket-create command.

    For example:

    ./couchbase-cli bucket-create \
--cluster 10.143.201.101:8091 \
--username Administrator \
--password password \
--bucket testBucket \
--bucket-type couchbase \
--bucket-ramsize 1024 \
--max-ttl 500000000 \
--durability-min-level persistToMajority \
--enable-flush 0

    The preceding example creates a Couchbase bucket named testBucket, with a RAM size of 1024 with the default storage backend (Magma with 128 vBucket). It sets a Maximum Time-to-Live and disables Flush. It also sets a Minimum Durability Level of persistToMajority.

    For more information about bucket-create and its parameters, see bucket-create in the Couchbase CLI reference.

    Create a Bucket with the REST API

    To create a bucket with the Couchbase REST API, use the POST http method, with the /pools/default/buckets endpoint.

    For example:

    curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d bucketType=couchbase \
-d ramQuota=512 \
-d durabilityMinLevel=majorityAndPersistActive

    The preceding example creates a Couchbase bucket named testBucket, with a RAM size of 512. It sets a Minimum Durability Level of majorityAndPersistActive. This bucket uses the default storage backend (Magma with 128 vBuckets).

    For more information about the /pools/default/buckets endpoint and its parameters, see Creating and Editing Buckets in the Buckets API reference.