C Client Library

Communicate with Couchbase Server using C

Note: Version 2.0 is the most recent release of this SDK.  It is recommended for all deployments.

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.

Getting Started

Here a quick screencast to introduce libcouchbase:

Download and Installation

The easiest way to get started with libcouchbase is by downloading one of the packages from a link at the right.

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

RHEL/CentOS 6.2

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

Then to install libcouchbase itself, run:

shell> sudo yum check-update && sudo yum install libcouchbase-devel

Ubuntu 11.10 Oneiric Ocelot (Debian unstable)

This may also work for later versions of Debian or Ubuntu which use libevent2.

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

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

Also make sure you have our 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 && sudo apt-get install libcouchbase-dev

Mac OS X

The homebrew recipe is available from the official homebrew repository. To install:

shell> brew install libcouchbase

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:

libcouchbase_t instance;    /* our libcouchbase instance */
libcouchbase_error_t oprc;  /* for checking various responses */

const char *host = "localhost:8091";
const char *username = NULL;
const char *passwd = NULL;
const char *bucket = "default";

instance = libcouchbase_create(host, username,
                               passwd, bucket, NULL);
if (instance == NULL) {
    fprintf(stderr, "Failed to create libcouchbase instance\n");
    return 1;
}

(void)libcouchbase_set_error_callback(instance, error_callback);
(void)libcouchbase_set_get_callback(instance, get_callback);

if (libcouchbase_connect(instance) != LIBCOUCHBASE_SUCCESS) {
    fprintf(stderr, "Failed to connect libcouchbase instance to server\n");
    return 1;
}

/* Wait for the connect to complete */
libcouchbase_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(libcouchbase_t instance,
                         const void *cookie,
                         libcouchbase_error_t error,
                         const void *key, size_t nkey,
                         const void *bytes, size_t nbytes,
                         uint32_t flags, uint64_t cas)
{
    (void)instance; (void)cookie; (void)cas;
    char *response_string = malloc(nbytes);
    strncpy(response_string, bytes, nbytes);
    fprintf(stderr, "Get callback received %s\n", response_string);
}

The API

In the associated documentation, you will find an API reference.