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.

Manage Buckets

      +
      Create, edit, and delete buckets to manage your data storage in a Couchbase Capella database.

      This page describes how you can create and manage buckets, using the Capella UI.

      A bucket is the named container in which you save your data. You may have up to 30 buckets in your database. You may organize the data within a bucket into different collections, according to content-type. A bucket’s data may be replicated across the database, to ensure that the data exists in multiple copies, and is thus highly available. A bucket’s data may also be replicated across different databases, potentially in different geographical locations.

      The Capella UI allows buckets to be easily defined, with default settings that support rapid prototyping and pre-production experimentation. For the subsequent design of sophisticated production systems, multiple configuration options are provided, to ensure heightened performance, integrity, and availability.

      Bucket Types

      Capella has two distinct bucket types:

      • Memory and Disk: Data is held in memory, and is also persisted to disk.

      • Memory Only Data is held in memory, but is not persisted to disk.

      For a detailed overview of buckets, see Buckets in the Couchbase Server documentation.

      The data held in a Memory Only bucket is lost in cases of cluster restart (whether planned or unplanned); and may also be lost due to the concurrent failure of multiple nodes. This is because the data in a Memory Only bucket is not held on disk.
      The Memory Only bucket must be provisioned with enough memory to be able to restore from backups. For more information about backup and restore, see Backup and Restore Data.

      Buckets and Storage

      Couchbase Capella databases use an append-only file-write format. This helps to ensure files' internal consistency, and reduces the risk of corruption. Every change made to a file —- whether an addition, a modification, or a deletion —- results in a new entry being created at the end of the file. A file whose user-data is diminished by deletion actually grows in size.

      File-sizes are periodically reduced by means of automated compaction. This process is known as purging. In Capella, purging occurs every 1 hour.

      Accessing Bucket Information

      To create, modify, or delete buckets from the Capella UI, you must have the Project Owner or Project Manager role for the database’s project. If you have the Organization Owner role, you have Project Owner access.

      Go to your database’s settings:

      1. On the Databases tab, select your database.

      2. Go to Settings  Buckets.

      If you have not yet created a bucket, the Create Bucket button is displayed in the middle of the page, allowing you to create your first bucket. See Create a Bucket.

      If you have already created one or more buckets, the Buckets Summary is displayed.

      Buckets Summary

      The Buckets Summary is a table that lists all buckets in the database. It includes the following information about each bucket:

      Bucket Name
      Documents
      Bucket Type
      Storage Backend
      Ops/Sec
      Disk
      Memory/Quota

      Clicking on the name of a bucket opens the Edit Bucket page for that bucket. The page shows information about the bucket’s current configuration. These details include conflict resolution, minimum durability level, replication, flush, and time to live settings. For more information, see Modify a Bucket.

      Create a Bucket

      To create a bucket in the Capella UI, you need the Project Owner or Project Manager role for your database’s project. If you have the Organization Owner role, you have Project Owner access.

      Go to your database’s settings:

      1. On the Databases tab, select your database.

      2. Go to Settings  Buckets.

      3. Click Create Bucket.

      4. In the Bucket Name field, enter a name for the new bucket. A bucket name can only contain upper or lower case letters, numbers, underscores (_), periods (.), dashes (-), and percentages (%). You cannot set a bucket name that exceeds 100 characters in length. You cannot change a bucket name after you create a bucket.

      5. In the Memory Quota (MiB) field, enter a Memory Quota for the bucket. A minimum of 100 MiB is required for a bucket with the Couchstore storage backend, and 1 GiB for a Magma bucket.

        Use the memory allocation graph to view the memory allocated to other buckets in the database, and the total amount of memory you can allocate to a new bucket.

        For more information about memory management in Capella, see Buckets and Storage.

      6. (Optional) Configure advanced settings for your bucket, or accept the default values. For more information about advanced bucket settings, see Configure Advanced Bucket Settings.

        You cannot configure any advanced settings for a bucket on a trial database. Upgrade your account to access all bucket customization options.

      7. Click Create Bucket.

      Configure Advanced Bucket Settings

      To configure advanced settings while you create a new bucket:

      1. Expand Show Advanced Settings.

      2. Choose a Bucket Type:

        • Select Memory and Disk if you need to persist your data to disk.

        • Select Memory Only if your data does not require disk-persistence, and can be maintained in memory only.

          If you create a Memory Only bucket, you cannot use App Endpoints, turn off a database, or use a database On/Off schedule.

          You also cannot change your bucket type after you create a bucket. For more information about the bucket types, see Bucket Types in the Couchbase Server documentation.

      3. (Memory and Disk Buckets Only) Choose a Storage Backend for the bucket:

        • Select Couchstore if your data set is relatively small, and fits easily into memory.

        • Select Magma if your data set is very large in relation to available memory, and therefore consistently requires high-speed disk-access.

          Couchstore buckets require a minimum memory allocation of 100 MiB. Magma buckets require 1 GiB. For more information about the differences between Couchstore and Magma, see Storage Engines in the Couchbase Server documentation.

          You cannot change your storage backend after you create a bucket.

          The memory quota specified for a bucket is allocated on a per-node basis. The total memory quota for the bucket is equal to the number of data nodes in the Service Group multiplied by the memory quota you specified. If the number of Data Service nodes in the database changes, the total memory allocated to the bucket changes based on the new number of data nodes.

          Example: If you have deployed Data Services on 3 nodes of your Capella database and then created a new bucket, the bucket memory quota will default to 100 MiB. This setting means each node will be allocated 100 MiB, giving the bucket a total of 300 MiB memory. If you then scale your database to run Data Services on six nodes at 100 MiB, then this will give 600 MiB maximum memory for the bucket.

      4. Choose the Conflict Resolution method for the bucket:

        • Select Sequence Number if you want the document with the higher sequence number to be used in case of a conflict between documents.

        • Select Timestamp if you want the document with the most recent timestamp to be used.

          Document conflicts occur during XDCR when a document has been modified differently in different locations, requiring one version of the document to be kept and the other discarded. You cannot change your conflict resolution method after you create a bucket. For more information about conflict resolution, see XDCR Conflict Resolution.

      5. (Memory Only Buckets Only) Choose an Ejection Policy for the bucket:

        • Select NRU (Not Recently Used) to ensure that if the bucket’s memory is full, documents that have not recently been used will be ejected, to reclaim memory for the saving of new documents.

        • Select No Ejection to ensure that if the bucket’s memory is full, all documents are retained, and attempts to save new documents fail.

          You cannot change your ejection policy after you create a bucket. For more information about ejection, see Ejection Policy in the Couchbase Server documentation.

      6. Choose the Minimum Durability Level for each write to the bucket:

        • None: Apply no durability level. This option is available for Memory and Disk and Memory Only buckets.

        • Replicate to Majority: Mutations replicate to a majority of the Data Service nodes, without persistence. This option is available for Memory and Disk and Memory Only buckets.

        • Majority and Persist to Active: Mutations replicate to a majority of the Data Service nodes. They’re also persisted—​written and synchronized to disk—​on the node hosting the active vBucket for the data. This option is available for Memory and Disk buckets only.

        • Persist to Majority: Mutations replicate to a majority of the Data Service nodes. They’re also persisted—​written and synchronized to disk—​on all nodes. This option is available for Memory and Disk buckets only.

          Durability helps to improve data integrity during failures. For more information about durability in Couchbase databases, see Durability in the Couchbase Server documentation.

      7. Set the Number of Replicas. Based on the number nodes in your database, you can choose from to create 1 to 3 replica copies of the data stored in this bucket. If you do not have the required number of nodes for a specific number of replicas, that option is unavailable.

      8. Turn Flush on or off. Flushing a bucket deletes all of its data permanently.

        To protect against inadvertent data loss, turn off Flush on production databases.

      9. Turn Time to Live (TTL) on or off. Enabling TTL allows you to set a maximum amount of time for which a document can exist before it’s automatically deleted. When enabled, this setting allows you to specify the time-period in seconds, minutes, hours, days, or weeks.

      10. Choose a backup schedule for the bucket according to the relative importance of the workload and data.

        1. Select Do Not Backup to not schedule any backups.

          Do Not Backup is not recommended for production databases. It’s intended for development databases or similar.

          To set a weekly incremental schedule, see the steps which follow.

        2. Choose Set Weekly Schedule.

        3. Choose the Day of the week when you want Capella to take the full backup. The default value is Sunday.

        4. Set the Start at time of day for the full backup.

          Select a Start at time when your application isn’t using Capella heavily unless you’ve chosen a database configuration with more capacity than you need.

        5. Use the Incremental Every list to set the frequency of incremental backups.

          If you change the Start at time, the next incremental backup might happen at a different time than you expect. Capella calculates the Incremental Value backward from the configured Start at time.

          For example, Incremental Every is 8 hours, and the Start at time is 4 AM. If the current time is 9 PM, Capella takes an incremental backup at 8 PM, an eight-hour interval backward from 4 AM. If you change the Start at to 6 AM, you would see another incremental backup at 10 PM, two hours after the last backup. The backup occurs at this time because Capella recalculates the eight-hour backup interval back from the new 6 AM Start at time.

        6. Select Cost Optimized Retention. When selected, the cost optimized retention policy applies to your bucket backup. For more information, see Cost Optimized Retention Policy.

        7. Set a Retention Time in line with your data retention policy.

          If you selected Cost Optimized Retention, the Retention Time applies only to the monthly restore point.

          Capella preserves each backup from 30 Days to 5 Years. After the retention time lapses, Capella schedules the backup for deletion.

          The Retention Time setting applies to all future backups for a bucket. Changes to this setting do not affect previous backups.

      11. To create the bucket with your chosen settings, click Create Bucket.

      Modify a Bucket

      You can modify some of a bucket’s settings after its creation.

      To modify a bucket, you need the Project Owner or Project Manager role for the database’s project. If you have the Organization Owner role, you have Project Owner access.

      Go to your database’s settings:

      1. On the Databases tab, select your database.

      2. Go to Settings  Buckets.

      3. In the Buckets Summary table, click the name of the bucket you want to modify.

      4. Edit the bucket’s settings.

        You can edit the following bucket settings:

        • Memory (MiB): Edit the amount of memory allocated to the bucket. A minimum of 100 MiB is required for a Couchstore storage backend bucket, and 1 GiB for a Magma bucket.

        • Minimum Durability Level: Choose a new minimum durability level. For more information, see the durability configuration instructions.

        • Number of Replicas: Choose the number of copies of this bucket’s data that Capella creates and maintains.

        • Flush: Choose to turn on or turn off flush. For more information, see the flush configuration instructions.

        • Time to Live: Choose to turn on or turn off time to live. For more information, see the time to live configuration instructions.

        • Backup Schedule: Change the backup schedule for the bucket. For more information about how to change a bucket’s backup schedule, see the backup schedule instructions.

      5. To save your changes to your bucket settings, click Update.

      Delete a Bucket

      Deleting a bucket deletes all of its contents. Backups for a deleted bucket might be available for a restore operation, based on the bucket’s previous Backup configuration.

      You can delete a bucket when it’s no longer needed, or when you need to replace all items within a bucket. Deleting and recreating a bucket is faster than deleting each document in a bucket.

      To delete a bucket, you need the Project Owner or Project Manager role for the database’s project. If you have the Organization Owner role, you have Project Owner access.

      If the bucket is the source of a replication, bucket deletion fails. You must delete all destination replication buckets before you can delete a source bucket.

      You can delete a destination replication bucket without deleting the source. Any configured replications, from the Replications page in your database settings, are automatically deleted after you delete a bucket.

      Go to your database’s settings:

      1. On the Databases tab, select your database.

      2. Go to Settings  Buckets.

      3. In the Buckets Summary table, click the name of the bucket you want to delete.

      4. Click Delete Bucket.

      5. Verify that you have chosen the correct bucket and then type delete into the provided field.

      6. Click Delete Bucket.

      Upon successful deletion, the bucket and all its data are deleted from the database.