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 Beta release of the Couchbase C SDK (libcouchbase). The API interface is stable, but could change for bug fixes during the Beta process. New features are likely to be added.

Documentation is incomplete, subject to change, and could 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:

lcb_CREATEOPTS *create_options = NULL;
lcb_createopts_create(&create_options, LCB_TYPE_CLUSTER);
lcb_createopts_connstr(create_options, argv[1], strlen(argv[1]));
// username, password
lcb_createopts_credentials(create_options, argv[2], strlen(argv[2]), argv[3], strlen(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);
lcb_createopts_destroy(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 planned introduction of Collections in a future release of the Couchbase Data Platform. The latest release, 6.5 Beta, 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.