You can create a new bucket with a POST command sent to the URI for buckets in a cluster. This can be used to create either a Couchbase or a Memcached type bucket. The bucket name cannot have a leading underscore.
To create a new Couchbase bucket, or edit the existing
parameters for an existing bucket, you can send a
POST to the REST API endpoint. You can also
use this same endpoint to get a list of buckets that exist for a
cluster.
| Method | POST /pools/default/buckets |
| Request Data | List of payload parameters for the new bucket |
| Response Data | JSON of the bucket confirmation or error condition |
| Authentication Required | yes |
| Payload Arguments | |
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 |
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. |
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. |
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. |
| Return Codes | |
| 202 | Accepted |
| 204 | Bad Request JSON with errors in the form of {"errors": { .... }} 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 |
When you create a bucket you must provide the
authType parameter:
If you set authType to
none, then you must specify a proxyPort
number.
If you set authType to
sasl, then you may optionally provide a
saslPassword parameter.
The ramQuotaMB parameter specifies how much
memory, in megabytes, you want to 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 will evict items on least-requested-item basis.
Couchbase Server may evict other infrequently used items
depending on object size, or whether or not an item is being
referenced.
In the case of Couchbase buckets, the system may return
temporary failures if the
ramQuotaMB is reached. The system
will try 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 will be
retrieved from disk.
For example:
shell> curl -X POST -u admin:password -d name=newbucket -d ramQuotaMB=200 -d authType=none \ -d replicaNumber=2 -d proxyPort=11215 http://localhost:8091/pools/default/buckets
The parameters for configuring the bucket are provided as payload data, with each parameter and value provided as a key/value pair, separated by an ampersand.
The HTTP request should include the parameters setting in the
payload of the POST request:
POST /pools/default/buckets HTTP/1.1 Host: localhost: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
If the bucket creation was successful, HTTP response 202 (Accepted) will be returned with empty content.
202 AcceptedIf the bucket could not be created, because the parameter was missing or incorrect, HTTP response 400 will be returned, with a JSON payload containing the error reason.