Couchbase Tools shipped with the Couchbase C Client Library (libcouchbase)

In this blog post, I will reveal some the less known features of the libcouchbase client library. It describes the libcouchbase tools which are collectively under cbc, the command originally written by Trond Norbye. You probably won’t use them for writing you high-level bindings or implementing your application, but they still useful in many ways.  They’re a great example of libcouchbase usage, they’re useful as diagnotic or debug tooling or you can even use them in your scripts.

Because there is a current release (1.0) of libcouchbase and a developer preview of the next release (1.1) which supports the new functionality coming in Couchbase Server 2.0, I will describe the 1.1 preview and will note which features are not accessible in current version.

[Edit] This blog was written for the new functionality in the tools shipping with libcouchbase 2.0. The latest version is now 3.0, and you can find out how to install it at https://docs.couchbase.com/c-sdk/3.0/hello-world/start-using-sdk.html and read a little more about the latest version of the tools at https://docs.couchbase.com/c-sdk/3.0/hello-world/cbc.html#command-line

After installation you will have the cbc command available and you can check the installed version:

Note that as of this writing, the currently released version is actually 1.1.0dp6, but packages for the most recent builds are available through the snapshot repository.  More on that at the end.

You could print out the all possible sub-commands using the helpsubcommand:

The “help” command accepts the command name as an argument and shows the command’s short description and all options the command can process, e.g. cbc help cp.

This command was added recently and may not be available in all versions. It is still possible to get list of commands in any version you have installed: just execute cbcwithout arguments and “cbc cp –help” correspondingly.

All commands are accessible either as subcommands or symlinks to the main binary, e.g. “cbc cp” and “cbc-cp”. The latter form is useful in shell scripts.

Connecting to Cluster

All commands accept a common set of arguments like --host, --bucket, --user, --password, and --timeout. These arguments should be specified to every command which requires interaction with cluster which need special connection options, like bucket name or authorization.

The option --enable-timingswill set make cbc record timings for all operations and output then to STDERR.

By default it will use localhostfor --host, defaultfor --bucket, nothing for --user/--password, and finally 2500000microseconds for --timeout.

If your connection settings are not the defaults, but you still doesn’t like typing them each time, we have solution: just put all of the settings into a file at $HOME/.cbcrcand all libcouchbase tools will use this before starting. The format is pretty simple: all empty lines and lines starting with #are skipped. Here’s my example config:

There is also a way to override the .cbcrcvalues but honour command line arguments: set environment variables. Couchbase cbc tools look at the following variables at startup: COUCHBASE_CLUSTER_URI, COUCHBASE_CLUSTER_USER, COUCHBASE_CLUSTER_PASSWORD, COUCHBASE_CLUSTER_BUCKET.

cbc-cpcbc-cp: Copy File(s) to the Cluster

This command copies file contents to the given cluster using filename for the key. For example the following command will store contents of the JSON file buzz.json:

After storing you will see the status on standard error. The command cbc-cpuses the file name as the key name and file contents as a value. It is possible to store several files quickly, as the command will pipeline the operations:

The command can also read file list from STDIN. For example you can feed output of the lscommand to cbc cp(note that filenames must be separated with a newline char):

cbc-create: Create Keys with Specific Options

This command creates the item in the cluster with the given options, like expiration time (--exptime), flags (--flag) or force it to use ADD command (--add) which will fail if the key already in the cluster. The command operates on a single key only and then waits for the value on STDIN (type a ^Dto insert the required EOF). For example:

cbc-cat: Print Keys to STDOUT

This command simply writes the contents of the all keys to STDOUT like Unix command cat(1). Also it writes useful info to STDERR. For example, lets output the key helloset above:

cbc-rm: Remove Key

This command removes given key from the cluster:

cbc-hash: Perform Hash Calculation

This command calculates the hash value of the key and locate the server which should store it, using the current cluster config. It also writes useful info about what vbucket is responsible for key, what the address is for that vbucket, the endpoint for requests for Couchbase Views and the list of replica nodes.

cbc-stats: Dump Cluster Statistics

This command returns tab-separated tuples of the server statistics. First is the node hostname with port, then stat key and stat value.

To show a simple scripting example, this is how you can calculate used memory on the whole cluster (this cluster has 5 nodes):

The stats output contains not only statistics from the live cluster but also its configuration parameters. You can get the maximum and default time (in seconds) for key locks (which we’ll want to know soon):

cbc-lock: Lock Key

This command locks the specified keys, making all mutation requests generate an error. It allows you to specify the expiration time (“–exptime”). You can inspect cluster default and maximum timeouts with the “cbc-stats” command as described above.

The cbc-lockcommand allows multiple keys.

cbc-unlock: Unlock Key

This command unlocks given keys. It accepts pairs of key and CAS values.  If they match, the server releases the lock.

cbc-verify: Verify Keys

This command verify the keys’ consistency. It compares the contents of the keys with corresponding files. If all is ok, it just return zero code at exit and prints nothing. So more interesting the case when something wrong. Let’s remove buzz.jsonand add something to barbie.json: