You are viewing the documentation for a prerelease version.

View Latest

Collections via CLI

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:

  1. 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.

  2. 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.

  3. 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
  4. 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.

  5. 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.

  6. 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.

  7. 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
  8. 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.

  9. 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
  10. 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.

  11. 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.