Creating and Editing Buckets

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

Description

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.

When editing bucket properties, be sure to specify all bucket properties. If a bucket property is not specified (whether or not you are changing the existing value), Couchbase Server may reset the property to the default. Even if you do not intend to change a certain property, re-specify the existing value to avoid this behavior.

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

authType

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.

bucketType

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.

conflictResolutionType

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

evictionPolicy

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.

flushEnabled

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.

name

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.

parallelDBAndViewCompaction

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

proxyPort

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.

ramQuotaMB

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.

replicaIndex

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.

replicaNumber

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.

saslPassword

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

threadsNumber

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.

maxTTL

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.

compressionMode

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.

Syntax

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]

Example

Curl request example:

curl -X POST -u Administrator:password http://127.0.0.1:8091/pools/default/buckets \
-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 http://127.0.0.1:8091/pools/default/buckets \
-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 http://10.142.180.101:8091/pools/default/buckets/testBucket \
-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
HTTP/1.1
Host: 10.5.2.54:8091
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: xx
name=newbucket&ramQuotaMB=20&authType=none&replicaNumber=2&proxyPort=11215

Response

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

202

Accepted

400

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

404

Object Not Found