A newer version of this documentation is available.

View Latest

Creating and Editing Buckets

  • reference
    To create and edit buckets, use the POST operation with the /pools/default/buckets URI.


    Buckets are created and edited with a POST sent to the REST URI endpoint for buckets in a cluster. This can be used to create either a Couchbase or a Memcached type bucket. Bucket names cannot have a leading underscore.

    This endpoint is also used to get a list of buckets that exist for a cluster.

    The REST API returns a successful response when preliminary files for a data bucket are created on one node. However, if a multi-node cluster is implemented, bucket creation may not have completed for all nodes when a response is sent. Therefore, it is possible that the bucket is not available for operations immediately after this REST call successful returns.

    To verify that a bucket is available, try to read a key from the bucket. If a ‘key not found’ error is received or the document for the key is returned, then the bucket exists and is available to all nodes in a cluster. Key requests can be issued via a Couchbase Server SDK with any node in the cluster. See the Couchbase Server Developer Guide for more information.

    HTTP method and URI

    POST /pools/default/buckets
    • Request data - List of payload parameters for the new bucket (in the body of the POST as x-www-form-urlencoded)

    • Response data - JSON of the bucket confirmation or an error condition

    • Authentication required - Yes

    Parameters for creating buckets:

    Table 1. Create bucket parameters
    Payload Arguments Description


    Required parameter. Type of authorization to be enabled for the new bucket as a string. Defaults to blank password if not specified. "sasl" enables authentication. "none" disables authentication.


    Required parameter. Type of bucket to be created. String value. "memcached" configures as Memcached bucket. "couchbase" configures as Couchbase bucket. This cannot be changed for a pre-existing bucket.


    Optional parameter. String value 'lww' (timestamp-based conflict resolution) or 'seqno' (sequence-number-based conflict resolution). This parameter defaults to 'seqno' if unspecified. This cannot be changed once a bucket has been created.


    Optional parameter, a string. Possible values are fullEviction and valueOnly. The default is valueOnly. This parameter determines what is ejected: only the value or the key, value, and all metadata.

    If you change the ejection policy of a pre-existing bucket then it will be restarted, resulting in temporary inaccessibility of data while the bucket warms up.


    Optional parameter. Enables the ‘flush all’ functionality on the specified bucket. Boolean. 1 enables flush all support, 0 disables flush all support. Defaults to 0.


    Required parameter. Name for new bucket. This cannot be changed for a pre-existing bucket. A bucket name can only contain characters in the ranges of A-Z, a-z, and 0-9; with the addition of the underscore, period, dash and percent characters; and can be no more than 100 characters in length.


    Optional parameter. String value. Indicates whether database and view files on disk can be compacted simultaneously. Defaults to "false."


    Required parameter. Numeric. Proxy port on which the bucket communicates. Must be a valid network port which is not already in use. You must provide a valid port number if the authorization type is not SASL.


    Required parameter. RAM Quota for new bucket in MB. Numeric. The minimum you can specify is 100, and the maximum can only be as great as the memory quota established for the node. If other buckets are associated with a node, RAM Quota can only be as large as the amount memory remaining for the node, accounting for the other bucket memory quota.


    Optional parameter. Boolean. 1 enable replica indexes for replica bucket data while 0 disables. Default of 1. This cannot be changed for a pre-existing bucket.


    Optional parameter. Numeric. Number of replicas to be configured for this bucket. Required parameter when creating a Couchbase bucket. Default 1, minimum 0, maximum 3.


    Optional Parameter. String. Password for SASL authentication. Required if SASL authentication has been enabled.


    Optional Parameter. Integer from 2 to 8. Change the number of concurrent readers and writers for the data bucket.

    If you change this setting for a pre-existing bucket then it will be restarted, resulting in temporary inaccessibility of data while the bucket warms up.


    Optional Parameter. Specifies the maximum TTL (time-to-live) for all documents in bucket in seconds. If enabled and a document is mutated with no TTL or a TTL greater than than the maximum, its TTL will be set to the maximum TTL. Setting this option to 0 disables the use of maxTTL, and the largest TTL that is allowed is 2147483647. This option is only available for Couchbase and Ephemeral buckets in Couchbase Enterprise Edition.


    Optional Parameter. Specifies the compression-mode of the bucket. There are three options; off, passive and active. All three modes are backwards compatible with older SDKs, where Couchbase Server will automatically uncompress documents for clients that do not understand the compression being used. This option is only available for Couchbase and Ephemeral buckets in Couchbase Enterprise Edition.

    Off: Couchbase Server will only compress document values when persisting to disk. This is suitable for use cases where compression could have a negative impact on performance. Please note it is expected that compression in most use cases will improve performance.

    Passive: Documents which were compressed by a client, or read compressed from disk will be stored compress in-memory. Couchbase Server will make no additional attempt to compress documents that are not already compressed.

    Active: Couchbase Server will actively and aggressively attempt to compress documents, even if they have not been received in a compressed format. This provides the benefits of compression even when the SDK clients are not complicit.

    When creating a bucket, the authType parameter must be provided:

    • If authType is set to none, then a proxyPort number must be specified.

    • If authType is set to sasl, then the saslPassword parameter may optionally be specified.

    The ramQuotaMB parameter specifies how much memory, in megabytes, is allocate to each node for the bucket. The minimum supported value is 100MB.

    • If the items stored in a memcached bucket take space beyond the ramQuotaMB, Couchbase Sever typically evicts items on a least-requested-item basis. Couchbase Server might evict other infrequently used items depending on object size or on whether or not an item is being referenced.

    • In the case of Couchbase buckets, the system might return temporary failures if the ramQuotaMB is reached. The system tries to keep 25% of the available ramQuotaMB free for new items by ejecting old items from occupying memory. In the event these items are later requested, they are retrieved from disk.


    Curl request syntax:

    curl -X POST -u [admin]:[password]  http://[ip_address]:8091/pools/default/buckets
      -d name=[new-bucket-name] -d ramQuotaMB=[value] -d authType=[none | sasl]
      -d replicaNumber=[value]
      -d proxyPort=[proxy-port]


    Curl request example:

    curl -X POST -u Administrator:password \
    -d name=newBucket -d ramQuotaMB=100 -d authType=none \
    -d replicaNumber=2 \
    -d proxyPort=11215

    Curl request example to set conflict resolution type. Set the parameter conflictResolutionType to lww during bucket creation. For example, use the following command to create a bucket on the source cluster:

    curl -X POST -u Administrator:asdasd http://<ip_address>:8091/pools/default/buckets
    -d name=newBucketSource -d conflictResolutionType=lww
    -d authType=sasl -d ramQuotaMB=4096
    -d saslPassword=passw0rd -d bucketType=couchbase

    Use the following command to create a bucket on the destination cluster:

    curl -X POST -u Administrator:asdasd http://<ip_address>:8091/pools/default/buckets
    -d name=newBucketDestination -d conflictResolutionType=lww
    -d authType=sasl -d ramQuotaMB=4096
    -d saslPassword=passw0rd -d bucketType=couchbase

    Curl request to set maximum Bucket Time-To-Live, and to establish a compression mode:

    curl -X POST -u Administrator:password \
    -d name=myTestBucket -d ramQuotaMB=100 \
    -d bucketType=couchbase -d maxTTL=20000 \
    -d compressionMode=Passive

    Curl request to edit an existing bucket:

    curl -X POST -u Administrator:password \
    -d bucketType=couchbase \
    -d autoCompactionDefined=false \
    -d evictionPolicy=valueOnly \
    -d threadsNumber=3 \
    -d replicaNumber=1 \
    -d compressionMode=passive \
    -d maxTTL=20000 \
    -d replicaIndex=0 \
    -d ramQuotaMB=100 \
    -d flushEnabled=0

    Raw HTTP request example:

    The parameters for configuring the bucket are provided as payload data. Each parameter and value are provided as a key/value pair where each pair is separated by an ampersand. Include the parameters setting in the payload of the HTTP POST request.

    POST /pools/default/buckets
    Content-Type: application/x-www-form-urlencoded; charset=UTF-8
    Authorization: Basic YWRtaW46YWRtaW4=
    Content-Length: xx


    If the bucket creation was successful, HTTP response 202 (Accepted) is returned with empty content.

    202 Accepted

    Response codes

    If the bucket could not be created, because the parameter was missing or incorrect, HTTP response 400 returns, with a JSON payload containing the error reason.

    Table 2. Create bucket error codes
    Error codes Description




    Bad Request JSON with errors in the form of {"errors": {…. }}. Possible error messages include:

    • name: Bucket with given name already exists

    • ramQuotaMB: RAM Quota is too large or too small

    • replicaNumber: Must be specified and must be a non-negative integer

    • proxyPort: port is invalid, port is already in use


    Object Not Found