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.

RHEL/CentOS 5.5

shell> sudo wget -O/etc/yum.repos.d/couchbase.repo http://packages.couchbase.com/rpm/couchbase-centos55-i386.repo
shell> sudo wget -O/etc/yum.repos.d/couchbase.repo http://packages.couchbase.com/rpm/couchbase-centos55-x86_64.repo

Standalone packages, if you cannot use repository:

RHEL/CentOS 6.2

shell> sudo wget -O/etc/yum.repos.d/couchbase.repo http://packages.couchbase.com/rpm/couchbase-centos62-i686.repo
shell> sudo wget -O/etc/yum.repos.d/couchbase.repo http://packages.couchbase.com/rpm/couchbase-centos62-x86_64.repo

Standalone packages, if you cannot use repository:

Then to install libcouchbase itself, run:

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

Ubuntu 12.04 Precise Pangolin (Debian unstable)

Also compatible with recent versions, which have libevent2.

shell> sudo wget -O/etc/apt/sources.list.d/couchbase.list http://packages.couchbase.com/ubuntu/couchbase-ubuntu1204.list

Standalone packages, if you cannot use repository:

Ubuntu 11.10 Oneiric Ocelot (Debian unstable)

Also compatible with recent versions, which have libevent2.

shell> sudo wget -O/etc/apt/sources.list.d/couchbase.list http://packages.couchbase.com/ubuntu/couchbase-ubuntu1110.list

Standalone packages, if you cannot use repository:

Ubuntu 10.04 Lucid Lynx (Debian stable or testing)

shell> sudo wget -O/etc/apt/sources.list.d/couchbase.list http://packages.couchbase.com/ubuntu/couchbase-ubuntu1004.list

Standalone packages, if you cannot use repository:

Also make sure you have the GPG key installed:

shell> wget -O- http://packages.couchbase.com/ubuntu/couchbase.key | sudo apt-key add - 

Then to install libcouchbase itself run:

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

We are building windows versions of libcouchbase with two different MS runtimes: 9th (Visual Studio 2008), 10th (Visual Studio 2010) and 11th (Visual Studio 2012) versions, to simplify linking for your application. Just choose the appropriate zip archive:

Compiler Architecture File
9 (VS 2008) x64 libcouchbase-2.3.0_amd64_vc9.zip
9 (VS 2008) x86 libcouchbase-2.3.0_x86_vc9.zip
10 (VS 2010) x64 libcouchbase-2.3.0_amd64_vc10.zip
10 (VS 2010) x86 libcouchbase-2.3.0_x86_vc10.zip
11 (VS 2012) x64 libcouchbase-2.3.0_amd64_vc11.zip
11 (VS 2012) x86 libcouchbase-2.3.0_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.0.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

It isn't mandatory, because your application is able to use its own IO plugin (like couchbase node.js client for example). The command below will disable building plugins for libev and libevent, and therefore the libcouchbase won't require and headers installed.

shell> ./configure --disable-plugins && 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"

Also the most recent development versions you can find in main source repository on github: github.com/couchbase/libcouchbase.

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 libcouchbase_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-22 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