You are viewing the documentation for a prerelease version.

View Latest

Install and Start Using the C SDK with Couchbase Server

The Couchbase C SDK (libcouchbase - LCB) enables you to interact with a Couchbase Server cluster from the C language. It is also used by the Node.js, PHP, and Python SDKs to communicate with the Couchbase Server.

These pages cover the Alpha of the Couchbase C SDK. As such they are likely to change without notice. This alpha code should not be used in production.

Documentation is incomplete, subject to change, and likely to contain broken links.

Installing the SDK

Hello Couchbase

Now you have the C client installed, you need to include the following in your first program:

struct lcb_create_st create_options = {0};
create_options.version = 3;
create_options.v.v3.type = LCB_TYPE_CLUSTER;
create_options.v.v3.connstr = argv[1];
create_options.v.v3.username = argv[2];
create_options.v.v3.passwd = argv[3];

Couchbase uses Role Based Access Control (RBAC) to control access to resources. Here we will use the Full Admin role created during installation of the Couchbase Data Platform. For production client code, you will want to use more appropriate, restrictive settings, but here we want to get you up and running quickly. If you’re developing client code on the same VM or machine as the Couchbase Server, your URI can be localhost.

lcb_STATUS rc; /* return code, that have to be checked */
lcb_INSTANCE *instance;
rc = lcb_create(&instance, &create_options);
rc = lcb_connect(instance);
rc = lcb_wait(instance);
rc = lcb_get_bootstrap_status(instance);

After initializing the cluster, we open a bucket:

static void open_callback(lcb_INSTANCE *instance, lcb_STATUS rc)
{
    printf("open bucket: %s\n", lcb_strerror_short(rc));
}

// associate instance with a bucket
lcb_set_open_callback(instance, open_callback);
const char *name = "bucket-name";
rc = lcb_open(instance, name, strlen(name)),

If you installed the travel sample data bucket, substitute travel-sample for bucket-name.

The 3.0 SDK is ready for the introduction of Collections in Cheshire Cat, the next release of the Couchbase Data Platform. The latest release, Mad Hatter, brings a limited Developer Preview of Collections, allowing Documents to be grouped by purpose or theme, according to specified Scope. Here we will use NULL for default collection, which covers the whole Bucket.

static void store_callback(lcb_INSTANCE *instance, int cbtype, const lcb_RESPSTORE *resp)
{
    const char *key;
    size_t nkey;
    uint64_t cas;
    lcb_respstore_key(resp, &key, &nkey);
    lcb_respstore_cas(resp, &cas);
    printf("status: %s, key: %.*s, CAS: 0x%" PRIx64 "\n",
       lcb_strerror_short(lcb_respstore_status(resp)), (int)nkey, key, cas);
}

lcb_install_callback3(instance, LCB_CALLBACK_STORE, (lcb_RESPCALLBACK)store_callback);

lcb_STATUS rc;
lcb_CMDSTORE *cmd;
const char *collection = NULL, *scope = NULL;
const char *key = "my-document";
const char *value = "{\"name\": \"mike\"}";
rc = lcb_cmdstore_create(&cmd, LCB_STORE_UPSERT);
rc = lcb_cmdstore_collection(cmd, collection, 0, scope, 0);
rc = lcb_cmdstore_key(cmd, key, strlen(key));
rc = lcb_cmdstore_value(cmd, value, strlen(value));
rc = lcb_store(instance, NULL, cmd);
rc = lcb_cmdstore_destroy(cmd);
rc = lcb_wait(instance);
static void get_callback(lcb_INSTANCE *instance, int cbtype, const lcb_RESPGET *resp)
{
    const char *key, *value;
    size_t nkey, nvalue;
    uint64_t cas;
    lcb_respget_key(resp, &key, &nkey);
    lcb_respget_value(resp, &value, &nvalue);
    lcb_respget_cas(resp, &cas);
    printf("status: %s, key: %.*s, CAS: 0x%" PRIx64 "\n",
       lcb_strerror_short(lcb_respget_status(resp)), (int)nkey, key, cas);
    printf("value:\n%s\n", (int)nvalue, value);
}

lcb_install_callback3(instance, LCB_CALLBACK_GET, (lcb_RESPCALLBACK)get_callback);

lcb_STATUS rc;
lcb_CMDGET *cmd;
const char *collection = NULL, *scope = NULL;
const char *key = "my-document";
rc = lcb_cmdget_create(&cmd);
rc = lcb_cmdget_collection(cmd, collection, 0, scope, 0);
rc = lcb_cmdget_key(cmd, key, strlen(key));
rc = lcb_get(instance, NULL, cmd);
rc = lcb_cmdget_destroy(cmd);
rc = lcb_wait(instance);

Additional Resources

The API reference is generated for each release and the latest can be found here. Older API references are linked from their respective sections in the Release Notes.

Couchbase welcomes community contributions to the C SDK. The C SDK source code is available on GitHub.