C Client Library

Couchbase Server for C Development

The C library provides fast access to documents in Couchbase Server 2.0. With JSON documents and Couchbase server 2.0 you have new ways to index and query data stored in the cluster through views. This client library, libcouchbase, also simplifies requests to Views through its handling of HTTP transport.

This Couchbase Client Library for C and C++ provides a complete interface to the functionality of Couchbase Server. For more on writing C programs with Couchbase Server Getting Started guide.

Step 0: Get a Server

Get & Install Couchbase Server. Come back here when you're done.

Step 1: Get a Client Library

Installing

Install either with the package commands for your operating system or by adding the Couchbase repository to your operating system's package manager.

Enterprise Linux (CentOS, Red Hat)

Find the right row for your distribution and architecture, and copy/paste the command in your shell

Version Architecture Command
5.x 32-Bit
shell> sudo wget -O /etc/yum.repos.d/couchbase.repo http://packages.couchbase.com/rpm/couchbase-centos55-i386.repo
5.x 64-Bit
shell> sudo wget -O /etc/yum.repos.d/couchbase.repo http://packages.couchbase.com/rpm/couchbase-centos55-x86_64.repo
6.x 32-Bit
shell> sudo wget -O /etc/yum.repos.d/couchbase.repo http://packages.couchbase.com/rpm/couchbase-centos62-i686.repo
6.x 64-Bit
shell> sudo wget -O /etc/yum.repos.d/couchbase.repo http://packages.couchbase.com/rpm/couchbase-centos62-x86_64.repo

Once done, execute the following (for all platforms)

shell> sudo yum check-update
shell> sudo yum install -y  libcouchbase2-libevent libcouchbase-devel

Ubuntu

Release Command
Lucid (10.04)
sudo wget -O/etc/apt/sources.list.d/couchbase.list http://packages.couchbase.com/ubuntu/couchbase-ubuntu1004.list
 
Precise (12.04)
sudo wget -O/etc/apt/sources.list.d/couchbase.list http://packages.couchbase.com/ubuntu/couchbase-ubuntu1204.list
 
Trusty (14.04)
sudo wget -O/etc/apt/sources.list.d/couchbase.list http://packages.couchbase.com/ubuntu/couchbase-ubuntu1404.list
 

Once done, do the following:

# Install GPG key
shell> wget -O- http://packages.couchbase.com/ubuntu/couchbase.key | sudo apt-key add - 
shell> sudo apt-get update
shell> sudo apt-get install libcouchbase2-libevent libcouchbase-dev

Mac OS X

This client library is available via a homebrew recipe.  After installing homebrew, to install libcouchbase:

shell> brew install libcouchbase

Note: if you have upgraded to Mountain Lion after having installed homebrew previously, The Hitchhiker's Guide to Riding A Mountain Lion is a good guide to resolving any problems.

Windows

Archives for Windows are included. Bundled in the archive are the header files (inside include), the dynamic library (bin/libcouchbase.dll), the import library (lib/libcouchbase.lib) and the debug variants (bin/libcouchbase_d.dll and lib/libcouchbase_d.lib). The cbc utility is included as well.

If you wish to link against libcouchbase from a Windows application, you must select the archive appropriate for the version of Visual Studio being used to compile your application.

Compiler Architecture File
9 (VS 2008) x64 libcouchbase-2.3.2_amd64_vc9.zip
9 (VS 2008) x86 libcouchbase-2.3.2_x86_vc9.zip
10 (VS 2010) x64 libcouchbase-2.3.2_amd64_vc10.zip
10 (VS 2010) x86 libcouchbase-2.3.2_x86_vc10.zip
11 (VS 2012) x64 libcouchbase-2.3.2_amd64_vc11.zip
11 (VS 2012) x86 libcouchbase-2.3.2_x86_vc11.zip.

Source Archives

If neither from listed above ways to install libcouchbase doesn't fit your needs, you can install it from the source tarball: libcouchbase-2.3.2.tar.gz

If you are using unix-like operation system, this typical spell will install it for you. It only depends on development headers either libevent or libev.

shell> ./configure && make && sudo make install

On MS Windows systems, you can use CMake to generate a project for Visual Studio, for example:

shell> cmake -G "Visual Studio 10"

Standalone Binary Packages

If you don't want to install from a repository, you may find standalone binary packages at the package archive. Select the tar archive appropriate for your distribution and extract it. The extracted contents contain the binary packages (e.g. deb or rpm) that you can manually install via your package manager.

Step 2: Try it out!

Concepts

The C client library, a.k.a. libcouchbase, is a callback oriented client which makes it very easy to write high performance programs. There are a few ways you can drive IO with the library. The simplest is to use the synchronous interface over the asynch internals of the library. More advanced programs will want to either call the lcb_wait() function after generating some operations, or drive the event loop themselves.

Connecting to a Cluster

Connecting to a cluster is straightforward:

struct lcb_create_st create_options;
lcb_t instance;
lcb_error_t err;
 
memset(&create_options, 0, sizeof(create_options));
create_options.v.v0.host = "myserver:8091";
create_options.v.v0.user = "mybucket";
create_options.v.v0.passwd = "secret";
create_options.v.v0.bucket = "mybucket";
 
err = lcb_create(&instance, &create_options);
if (err != LCB_SUCCESS) {
    fprintf(stderr, "Failed to create libcouchbase instance: %s\n",
            lcb_strerror(NULL, err));
    return 1;
}
 
/* set up the handler to catch all errors! */
lcb_set_error_callback(instance, error_callback);
 
/* initiate the connect sequence in libcouchbase  */
err = lcb_connect(instance);
if (err != LCB_SUCCESS) {
    fprintf(stderr, "Failed to initiate connect: %s\n",
            lcb_strerror(NULL, err));
    return 1;
}
 
/* run the event loop and wait until we've connected */
lcb_wait(instance);

Using Callbacks

Callbacks are simple functions to handle the result of operations. For example:

/* the callback invoked by the library when receiving a get response */
static void get_callback(lcb_t instance,
                         const void *cookie,
                         lcb_error_t error,
                         const lcb_get_resp_t *resp)
{
    if (error != LCB_SUCCESS) {
        fprintf(stderr, "Failed to retrieve \"");
        fwrite(resp->v.v0.key, 1, resp->v.v0.nkey, stderr);
        fprintf(stderr, "\": %s\n", lcb_strerror(instance, error));
    } else {
        fprintf(stderr, "Data for key: \"");
        fwrite(resp->v.v0.key, 1, resp->v.v0.nkey, stderr);
        fprintf(stderr, "\" is : ");
        fwrite(resp->v.v0.bytes, 1, resp->v.v0.nbytes, stderr);
    }
    (void)cookie; /* ignore */
}

Callbacks can be set up for all of your operations called in libcouchbase. In the API, you'll note the use of a "cookie". This is opaque data from your application which is associated with the request. Underlying libcouchbase will not inspect the field, or send it to the server.

Putting the connect logic and the get callback all together into a complete program with the include headers would be:

#include <libcouchbase/couchbase.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
 
static void error_callback(lcb_t instance,
                           lcb_error_t err,
                           const char *errinfo)
{
    fprintf(stderr, "Error %s: %s", lcb_strerror(instance, err),
            errinfo ? errinfo : "");
    exit(EXIT_FAILURE);
}
 
/* the callback invoked by the library when receiving a get response */
static void get_callback(lcb_t instance,
                         const void *cookie,
                         lcb_error_t error,
                         const lcb_get_resp_t *resp)
{
    if (error != LCB_SUCCESS) {
        fprintf(stderr, "Failed to retrieve \"");
        fwrite(resp->v.v0.key, 1, resp->v.v0.nkey, stderr);
        fprintf(stderr, "\": %s\n", lcb_strerror(instance, error));
    } else {
        fprintf(stderr, "Data for key: \"");
        fwrite(resp->v.v0.key, 1, resp->v.v0.nkey, stderr);
        fprintf(stderr, "\" is:\n");
        fwrite(resp->v.v0.bytes, 1, resp->v.v0.nbytes, stderr);
        fprintf(stderr, "\n");
    }
    (void)cookie; /* ignore */
}
 
int main(void)
{
    struct lcb_create_st create_options;
    lcb_t instance;
    lcb_error_t err;
 
    memset(&create_options, 0, sizeof(create_options));
    create_options.v.v0.host = "localhost:8091";
    create_options.v.v0.user = "beer-sample";
    create_options.v.v0.passwd = NULL;
    create_options.v.v0.bucket = "beer-sample";
 
    err = lcb_create(&instance, &create_options);
    if (err != LCB_SUCCESS) {
        fprintf(stderr, "Failed to create libcouchbase instance: %s\n",
                lcb_strerror(NULL, err));
        return 1;
    }
 
    /* set up the handler to catch all errors */
    lcb_set_error_callback(instance, error_callback);
 
    /* initiate the connect sequence in libcouchbase */
    err = lcb_connect(instance);
    if (err != LCB_SUCCESS) {
        fprintf(stderr, "Failed to initiate connect: %s\n",
                lcb_strerror(NULL, err));
        return 1;
    }
 
    /* run the event loop and wait until we've connected */
    lcb_wait(instance);
 
    /* set up a callback for our get requests  */
    lcb_set_get_callback(instance, get_callback);
 
    {
        lcb_get_cmd_t cmd;
        const lcb_get_cmd_t *commands[1];
 
        commands[0] = &cmd;
        memset(&cmd, 0, sizeof(cmd));
        cmd.v.v0.key = "second_street_brewery";
        cmd.v.v0.nkey = strlen(cmd.v.v0.key);
 
        err = lcb_get(instance, NULL, 1, commands);
        if (err != LCB_SUCCESS) {
            fprintf(stderr, "Failed to get: %s\n",
                    lcb_strerror(NULL, err));
            return 1;
        }
    }
 
    lcb_wait(instance);
 
    lcb_destroy(instance);
    exit(EXIT_SUCCESS);
}

Assuming the local Couchbase Server installed with beer-sample bucket loaded, the code above can be compiled and run:

shell> gcc -o sample -lcouchbase sample.c
shell> ./sample 
Data for key: "second_street_brewery" is:
{"name":"Second Street Brewery","city":"Santa Fe","state":"New Mexico","code":"87505","country":"United States","phone":"1-505-982-3030","website":"http://www.secondstreetbrewery.com/","type":"brewery","updated":"2010-07-20:00:20","description":"","address":["1814 Second Street"],"geo":{"accuracy":"RANGE_INTERPOLATED","lat":35.6631,"lon":-105.966}}

The API

In addition to the library headers installed with the client library, in the associated documentation, you will find an API reference.

For unix-like systems we are installing man pages, checkout index man page at man libcouchbase