Start Using the SDK
Edit this article in GitHub
Version 2.3

Start Using the SDK

The Couchbase C SDK (libcouchbase) enables C and C++ programs to access a Couchbase cluster. The C SDK is also commonly used as a core dependency of SDKs written in other language to provide a common implementation and high performance.

Features

  • Cross-Platform: Officially supported on Linux, Mac OS X, and Microsoft Windows (though it is also known to run on other platforms).
  • Key-Value (CRUD) operations (lcb_get3, lcb_store3, etc.)
  • N1QL query operations (lcb_n1ql_query)
  • Map Reduce (view) query operations (lcb_view_query)
  • Secure SSL connections (Couchbase Enterprise only)
  • Pluggable non-blocking event loops such as libevent, libev, and libuv- integrate with your own non-blocking application, or use lcb_wait in blocking code
Note that SSL and N1QL features depend on server support. See Compatibility of Couchbase Features, Couchbase Versions and the Couchbase C (libcouchbase) SDK to see which server versions support which features.

Platform support and installation

The Couchbase C SDK can be installed via apt or deb repositories on Linux; homebrew on Mac OS X; and binary archives for Microsoft Windows. It may also be built from source on any of the platforms mentioned above, and more.

Installing on Linux

For installation on Linux, install the couchbase-release repository, and then install the libcouchbase packages. The following examples download and install couchbase-release repsitory, a C and C++ compiler, and the C SDK core (libcouchbase2-core), command line tools (libcouchbase2-bin), and the development tools (libcouchbase-devel [RPM] or libcouchbase-dev [DEB]).

Debian and Ubuntu
# Only needed during first-time setup:
wget http://packages.couchbase.com/releases/couchbase-release/couchbase-release-1.0-3-amd64.deb
sudo dpkg -i couchbase-release-1.0-3-amd64.deb
# Will install or upgrade packages
sudo apt-get update
sudo apt-get install libcouchbase-dev libcouchbase2-bin build-essential
RHEL and CentOS
# Only needed during first-time setup:
wget http://packages.couchbase.com/releases/couchbase-release/couchbase-release-1.0-2-x86_64.rpm
sudo rpm -iv couchbase-release-1.0-2-x86_64.rpm
# Will install or upgrade existing packages
sudo yum install libcouchbase-devel libcouchbase2-bin gcc gcc-c++
Note: You should install the libcouchbase2-libevent or libcouchbase2-libev plugin in case your application will use more than 1024 file descriptors. The default select() based event loop only supports 1024 file descriptors.

Installation on Mac OS X

To install the library on Mac OS X, first install the de-facto package manager for OS X: homebrew. Once homebrew is configured:
brew update # get list of latest packages
brew install libcouchbase

Installation on Microsoft Windows

See Installation and Release Notes section for details.

Installing from Source Code

You may install the library from source code, either via a repository checkout or using a release tarball (download links may be found at Installation and Release Notes. Follow the instructions in the README.markdown file at the top of the source tree.

Documentation and Examples

Information on new features, fixes, known issues as well as information on how to install older release versions is available in the release notes.

Hello Couchbase

A simple example below (requires version 2.5.6 or higher to function). Error checking is omitted for brevity.
#include <libcouchbase/couchbase.h>

static void
opCallback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb) {
    fprintf(stderr, "%.*s: %s... ", (int)rb->nkey, rb->key, lcb_strcbtype(cbtype));
    if (rb->rc != LCB_SUCCESS) {
        fprintf(stderr, "%s\n", lcb_strerror(NULL, rb->rc));
    } else {
        fprintf(stderr, "OK");
        if (cbtype == LCB_CALLBACK_GET) {
            const lcb_RESPGET *rg = (const lcb_RESPGET *)rb;
            fprintf(stderr, "... Value: %.*s\n", (int)rg->nvalue, rg->value);
        } else {
            fprintf(stderr, "\n");
        }
    }
}

int main(int argc, char **argv)
{
    assert(lcb_version_g >= 0x020506 && "This example requires 2.5.6 or greater");

    lcb_t instance;
    lcb_create_st options;
    memset(&options, 0, sizeof options);
    options.version = 3;
    options.v.v3.connstr = "couchbase://localhost/bucketname";
    options.v.v3.username = "mark";
    options.v.v3.passwd = "s3cr3t";
    lcb_error_t rc = lcb_create(&instance, &options);
    lcb_create(&instance, &options);
    lcb_connect(instance);
    lcb_wait(instance);

    lcb_install_callback3(instance, LCB_CALLBACK_GET, opCallback);
    lcb_install_callback3(instance, LCB_CALLBACK_STORE, opCallback);

    lcb_CMDSTORE scmd = { 0 };
    LCB_CMD_SET_KEY(&scmd, "key", 3);
    LCB_CMD_SET_VALUE(&scmd, "true", 4);
    scmd.operation = LCB_SET;
    lcb_store3(instance, NULL, &scmd);
    lcb_wait(instance);

    lcb_CMDGET gcmd = { 0 };
    LCB_CMD_SET_KEY(&gcmd, "key", 3);
    lcb_get3(instance, NULL, &gcmd);
    lcb_wait(instance);
    lcb_destroy(instance);

    return 0;
}

Scheduling, Blocking and non-blocking

The library is designed to be non-blocking. As opposed to a blocking API where API calls themselves perform the operations and return results, the C SDK's non-blocking API schedules the operation, with the result of the operation being passed to a callback which is invoked when ready. The readiness and completion of an operation will only happen when the library has had a chance to send the operation to the server and await a response from the network.

Most operations in the library do not execute the operation immediately, but rather schedule it to be executed when it is possible to perform network I/O.

The lcb_wait() function will instruct the library to send all scheduled operations to the cluster and await the results for those operations. As results become available, designated callbacks (specified using lcb_install_callback3()) are invoked with the results.

If your application is built on top of an event loop (for example, libev) you can integrate the C SDK to perform its I/O within the context of your event loop, avoiding the need to block for I/O with lcb_wait().

Library Handle and Server Connections

Almost all operations within the library are done with a library handle of type lcb_t. The lcb_t is a handle representing a connection to a single bucket (though it is possible to access other buckets as well for certain operations).

An lcb_t is created using the lcb_create() function. Once created the handle must be connected: lcb_connect() schedules the connection and lcb_wait waits for the connection to complete. Once lcb_wait returns, lcb_get_bootstrap_status may be used to determine if the connection completed successfully.

Once the handle has been successfully connected it may then be used for data access.

When the library handle is no longer needed, it can be destroyed via lcb_destroy().

API Reference

The API reference is generated for each version. The API reference for version 2.8.0 is at http://docs.couchbase.com/sdk-api/couchbase-c-client-2.8.0