A newer version of this documentation is available.

View Latest

Getting started

To follow the tradition of programming tutorials, here’s a Hello Couchbase example to help you get started with the C SDK. Running this example will verify that the C SDK is installed properly on your machine and show you how to perform some simple operations on Couchbase Server.

Building and running Hello Couchbase

Here’s the Hello Couchbase code:

hello.c
#include <libcouchbase/couchbase.h>
#include <stdio.h>
#include <stdlib.h>

static void storage_callback(lcb_t instance, const void *cookie, lcb_storage_t op,
   lcb_error_t err, const lcb_store_resp_t *resp)
{
  printf("Stored %.*s\n", (int)resp->v.v0.nkey, resp->v.v0.key);
}

static void get_callback(lcb_t instance, const void *cookie, lcb_error_t err,
   const lcb_get_resp_t *resp)
{
  printf("Retrieved key %.*s\n", (int)resp->v.v0.nkey, resp->v.v0.key);
  printf("Value is %.*s\n", (int)resp->v.v0.nbytes, resp->v.v0.bytes);
}

int main(void)
{

  // initializing

  struct lcb_create_st cropts = { 0 };
  cropts.version = 3;
  cropts.v.v3.connstr = "couchbase://localhost/default";
  lcb_error_t err;
  lcb_t instance;
  err = lcb_create(&instance, &cropts);
  if (err != LCB_SUCCESS) {
    printf("Couldn't create instance!\n");
    exit(1);
  }

  // connecting

  lcb_connect(instance);
  lcb_wait(instance);
  if ( (err = lcb_get_bootstrap_status(instance)) != LCB_SUCCESS ) {
    printf("Couldn't bootstrap!\n");
    exit(1);
  }

  // installing callbacks

  lcb_set_store_callback(instance, storage_callback);
  lcb_set_get_callback(instance, get_callback);


  // scheduling operations

  lcb_store_cmd_t scmd = { 0 };
  const lcb_store_cmd_t *scmdlist = &scmd;
  scmd.v.v0.key = "Hello";
  scmd.v.v0.nkey = 5;
  scmd.v.v0.bytes = "Couchbase";
  scmd.v.v0.nbytes = 9;
  scmd.v.v0.operation = LCB_SET;
  err = lcb_store(instance, NULL, 1, &scmdlist);
  if (err != LCB_SUCCESS) {
    printf("Couldn't schedule storage operation!\n");
    exit(1);
  }
  lcb_wait(instance); //storage_callback is invoked here

  lcb_get_cmd_t gcmd = { 0 };
  const lcb_get_cmd_t *gcmdlist = &gcmd;
  gcmd.v.v0.key = "Hello";
  gcmd.v.v0.nkey = 5;
  err = lcb_get(instance, NULL, 1, &gcmdlist);
  if (err != LCB_SUCCESS) {
    printf("Couldn't schedule get operation!\n");
    exit(1);
  }
  lcb_wait(instance); // get_callback is invoked here
  lcb_destroy(instance);
  return 0;
}

Compile and run Hello Couchbase by using the following commands:

$ gcc hello.c -o hello -lcouchbase
$ ./hello

The program output, which is generated by the callback functions, looks like this:

Stored Hello
Retrieved key Hello
Value is Couchbase
For brevity, examples in this manual are written using the C99 standard. Some compilers (notably, Visual Studio versions earlier than 2013) do not support the C99 standard (supporting only C89). A minimal example, somewhat equivalent to the one above, you can find in the repository.

Code description

The following points explain each step in the Hello Couchbase code example:

  • Initializing

    A connection to a bucket within the cluster is represented by the lcb_t handle that is a library-allocated handle. The handle is first initialized with a Connection String containing the server’s address (localhost) and the bucket name (default). The connection string is placed into the creation options structure (lcb_create_st), and that is passed to the lcb_create() function that creates the new instance.

  • Connecting

    After the instance has been initialized, it is ready to be connected. Use the lcb_connect`() function, which schedules a connection to the network. After the connection has been scheduled, you must wait for the connection to complete. Waiting for operations to complete is done by the [.api]`lcb_wait() call, which blocks the application. (The library can also be used in non-blocking models, but that is not shown in this example.) After the wait is complete, the lcb_get_bootstrap_status() function is called to determine whether the initial connection was successful.

  • Installing callbacks

    The library delivers most operation status codes and responses via specially installed callbacks that are invoked for each operation of a given type. This example installs callbacks for storage operations and retrieval operations. The contents of the arguments for each callback consists of the response data for a given operation (the resp argument) and user-associated context information for the operation (the cookie argument). It also contains success/failure information in the err argument.

  • Scheduling operations

    After the callbacks have been installed, operations to store and retrieve an item from the cluster are initialized. The operations are expressed in terms of command structures. The command structure for storing an item is lcb_store_cmd_t and is initialized with the key and value and item to be stored. The command structure for retrieving an item is lcb_get_cmd_t and is initialized with the key to retrieve.