Collections via CLI

Developer Preview

Collections can be managed by means of the Couchbase CLI.

Using the CLI

The following sequence of CLI commands demonstrates how to create, examine, and delete scopes and collections. It assumes that Couchbase Server has been installed, initialized, and provisioned on a Ubuntu system. Note, however, that the sequence should work identically on other Linux systems; as well as on MacOS and Windows systems.

At the command-line prompt, proceed as follows:

Create a bucket, named test-bucket, using the couchbase-cli bucket-create command.

/opt/couchbase/bin/couchbase-cli bucket-create \
--cluster localhost:8091 --username Administrator \
--password password --bucket testBucket --bucket-type couchbase \
--bucket-ramsize 100

If the command is successful, the following output is displayed:

SUCCESS: Bucket created

For more information on this command, see bucket-create.

Using the cbstats command, check that collections have been enabled, and check the maximum size for collections, then for scopes:
```
/opt/couchbase/bin/cbstats -u Administrator -p password localhost:11210 -b testBucket all | grep collections
```
The following output is displayed:
```
ep_collections_enabled:                                true
ep_collections_max_size:                               1000
```
This indicates that collections are enabled, and that a maximum number 1000 collections can be created for the bucket.

Check the maximum size for scopes:
```
/opt/couchbase/bin/cbstats -u Administrator -p password localhost:11210 -b testBucket all | grep scopes
```
The following output is displayed:
```
ep_scopes_max_size:                                    100
```
The output indicates that a maximum number of 100 scopes can be created for the bucket.
Create a scope, using the couchbase-cli collection-manage command. The --bucket parameter specifies the name of the bucket within which the scope will be created; and the --create-scope parameter specifies the name of the scope.
```
/opt/couchbase/bin/couchbase-cli collection-manage \
--cluster http://localhost:8091 \
--username Administrator \
--password password \
--bucket testBucket \
--create-scope my_scope
```
If the command is successful, the following output is displayed:
```
SUCCESS: Scope created
```
List the scopes now contained by the bucket testBucket.
```
/opt/couchbase/bin/couchbase-cli collection-manage \
-c localhost \
--username Administrator \
--password password \
--bucket testBucket \
--list-scopes
```
The following output is displayed:
```
_default
my_scope
```
This indicates that testBucket now contains two scopes. One is the _default, the other is the newly created scope my_scope.
Use collection-manage successively, to create two collections within my_scope. The name of the collection to be created is specified with the --create-collection parameter, using a path in dot format (that is, in the form scope-name.collection-name) to specify the destination scope. Then, list the collections in the scope, using collection-manage with the --list-collections parameter.

Create the my_scope.my_collection_in_my_scope_1 collection:
```
/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \
--username Administrator \
--password password \
--bucket testBucket \
--create-collection my_scope.my_collection_in_my_scope_1
```
On success, the output is as follows:
```
SUCCESS: Collection created
```
Create the my_scope.my_collection_in_my_scope_2 collection:
```
/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \
--username Administrator \
--password password \
--bucket testBucket \
--create-collection my_scope.my_collection_in_my_scope_2
```
On success, the output is as again follows:
```
SUCCESS: Collection created
```
Now, list all collections:
```
/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \
--username Administrator \
--password password \
--bucket testBucket \
--list-collections my_scope
```
If the command is successful, the output features a list of all created collections within my_scope:
```
my_collection_in_my_scope_1
my_collection_in_my_scope_2
```
The output indicates that my_scope now contains the collections my_collection_in_my_scope_1 and my_collection_in_my_scope_1.

Create a collection in the _default scope, and then list collections within that scope.

/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \
--username Administrator \
--password password \
--bucket testBucket \
--create-collection _default.my_collection_in_default_scope

On success, the following output is displayed:

SUCCESS: Collection created

Now, list collections within the scope:

/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \
--username Administrator \
--password password \
--bucket testBucket \
--list-collections _default

On success, a list of the collections in the scope is displayed:

my_collection_in_default_scope
_default

The output indicates that the _default scope now contains two collections, which are the _default collection, and the newly created collection my_collection_in_default_scope.

Create two documents, within the default scope and collection, using the cbc create command. Note that if no scope or collection is explicitly specified, the default scope and collection are assumed.

/opt/couchbase/bin/cbc create -u Administrator -P password testDocument1 \
-U couchbase://localhost/testBucket \
-V '{"key1" : "value1"}'

On success, this produces output indicating that the named document has been saved, and providing its CAS number.

testDocument1       Stored. CAS=0x15833ec67e800000

Now, create the second document:

/opt/couchbase/bin/cbc create -u Administrator -P password testDocument2 \
-U couchbase://10.143.192.101/testBucket \
-V '{"key2" : "value2"}'

On success, the output is as follows:

testDocument2       Stored. CAS=0x15833ec889540000

Display statistics on existing collections, using the cbstats command, specifying the collections parameter.

/opt/couchbase/bin/cbstats -u Administrator -p password \
-b testBucket localhost:11210 collections

Statistics are displayed as follows:

collection:0x0:items:         2
collection:0x8:items:         0
collection:0x9:items:         0
collection:0xa:items:         0
manifest:collection:0x0:name: _default
manifest:collection:0x8:name: my_collection_in_my_scope_1
manifest:collection:0x9:name: my_collection_in_my_scope_2
manifest:collection:0xa:name: my_collection_in_default_scope
manifest:collections:         4
manifest:default_exists:      true
manifest:uid:                 4

Note that the output identifies the _default collection as 0x0, and indicates that this contains 2 items: these correspond to the two documents previously created with cbc create.

Again display statistics on existing collections using the cbstats command, this time specifying the collections-details parameter.

/opt/couchbase/bin/cbstats -u Administrator -p password -b testBucket \
localhost:11210 collections-details

Statistics are displayed as follows:

manifest:collection:0x0:name:                      _default
manifest:collection:0x8:name:                      my_collection_in_my_scope_1
manifest:collection:0x9:name:                      my_collection_in_my_scope_2
manifest:collection:0xa:name:                      my_collection_in_default_scope
manifest:collections:                              4
manifest:default_exists:                           true
manifest:uid:                                      4
vb_0:collection:0x0:entry:high_seqno:              0
vb_0:collection:0x0:entry:items:                   0
vb_0:collection:0x0:entry:persisted_high_seqno:    0
vb_0:collection:0x0:entry:scope:                   0
vb_0:collection:0x0:entry:start_seqno:             0
vb_0:collection:0x8:entry:high_seqno:              2
vb_0:collection:0x8:entry:items:                   0
vb_0:collection:0x8:entry:persisted_high_seqno:    2
vb_0:collection:0x8:entry:scope:                   8
vb_0:collection:0x8:entry:start_seqno:             2
vb_0:collection:0x9:entry:high_seqno:              3
vb_0:collection:0x9:entry:items:                   0
 	.
	.

The output, which is presented here in truncated form, provides additional details on scopes, collections, and their content; including sequence numbers, uid numbers, and per-vBucket information. Note that an identifying vBucket-number can be specified, to produce output for that vBucket alone:

/opt/couchbase/bin/cbstats -u Administrator -p password -b testBucket localhost:11210 collections-details 8

The number 8 having been specified, displayed statistics are for vBucket 8 only:

vb_8:collection:0x0:entry:high_seqno:           0
vb_8:collection:0x0:entry:items:                0
vb_8:collection:0x0:entry:persisted_high_seqno: 0
vb_8:collection:0x0:entry:scope:                0
vb_8:collection:0x0:entry:start_seqno:          0
vb_8:collection:0x8:entry:high_seqno:           2
vb_8:collection:0x8:entry:items:                0
vb_8:collection:0x8:entry:persisted_high_seqno: 2
vb_8:collection:0x8:entry:scope:                8
vb_8:collection:0x8:entry:start_seqno:          2
vb_8:collection:0x9:entry:high_seqno:           3
vb_8:collection:0x9:entry:items:                0
vb_8:collection:0x9:entry:persisted_high_seqno: 3
vb_8:collection:0x9:entry:scope:                8
vb_8:collection:0x9:entry:start_seqno:          3
vb_8:collection:0xa:entry:high_seqno:           4
vb_8:collection:0xa:entry:items:                0
vb_8:collection:0xa:entry:persisted_high_seqno: 4
vb_8:collection:0xa:entry:scope:                0
vb_8:collection:0xa:entry:start_seqno:          4
vb_8:manifest:default_exists:                   true
vb_8:manifest:entries:                          4

Drop a collection from the created scope, then list collections within that scope.

/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \
--username Administrator \
--password password \
--bucket testBucket \
--drop-collection my_scope.my_collection_in_my_scope_1

If the command is successful, the following is displayed:

SUCCESS: Collection deleted

Note that in this context, deleted means dropped.

/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \
--username Administrator \
--password password \
--bucket testBucket \
--list-collections my_scope

Output features each collection in the specified scope:

my_collection_in_my_scope_2

The output indicates that the collection my_collection_in_my_scope_1 has now been dropped from my_scope.

Drop the created scope, then list scopes.

/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \
--username Administrator \
--password password \
--bucket testBucket \
--drop-scope my_scope

On success, the following output is displayed:

SUCCESS: Scope deleted

List all remaining scopes:

/opt/couchbase/bin/couchbase-cli collection-manage -c localhost \
--username Administrator \
--password password \
--bucket testBucket \
--list-scopes

The following output is displayed:

_default

This indicates that my_scope, and the collection it contained, my_collection_in_my_scope_2, have been dropped.

This concludes the sequence of commands.