Introduction

This guide provides information for developers who want to use the Couchbase C SDK to build applications that use Couchbase Server.

Getting Started

Now that you’ve installed Couchbase and have probably created a cluster of Couchbase servers, you will need to use a client library to save and retrieve data from the cluster. The Couchbase C client library, also known as libcouchbase, is one way of doing so.

Here’s a quick outline of what you’ll learn in this chapter:

  • How to obtain the client library.

  • How to build the client library from source (optional).

  • Write a simple program to demonstrate connecting to Couchbase and saving some data.

Downloading the Couchbase Client Library

Download the latest client library from the Couchbase download site. It is available as a source archive in both .zip and .tar.gz

Installing on Linux using Packages

Packages are provided for RedHat and Ubuntu Linux systems by seeding your package manager with the Couchbase repo information. The method for installation this way is dependent on your platform:

RedHat/CentOS

You must seed RPM with a new source, which is depedendent on your RedHat version:

Then to install libcouchbase itself, run:

shell> sudo yum check-update
shell> sudo yum install -y  libcouchbase2 libcouchbase-devel

Ubuntu

You must update the apt-get repository:

Also make sure you have the 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
shell> sudo apt-get install libcouchbase2 libcouchbase-dev

Installing using packages on Mac OS X

This client library is available via a homebrew recipe. After installing homebrew, to install libcouchbase:

shell> brew install \
          https://github.com/couchbase/homebrew/raw/stable/Library/Formula/libcouchbase.rb

Installing from Source: Linux and Mac OS X

Installation is like many common libraries, following the ./configure, make, make install conventions.

For libvbucket, extract the archive then cd into the directory and run:

shell> ./configure
shell> make install

Standard configure options such as --prefix can be passed to the configure command. Running./configure with –help with provide additional information on configuration options.

For libcouchbase, extract the archive, then cd into the directory and run:

shell> ./configure CPPFLAGS="-I/opt/couchbase/include" --disable-couchbasemock
shell> make install

The --disable-couchbasemock simply disables some tests which are common during development of libcouchbase, but not required when installing a release.

Installing from Source: Microsoft Windows

Building and installing on Microsoft Windows depends on nmake and tools in Microsoft Visual Studio 2010.

Open the Visual Studio Command Prompt, and navigate to the directory for the extracted archive for libvbucket. The NMakefile defines an INSTALL variable as C:\local. Edit the NMakefile if you wish to change the installation location. Then build and install libvbucket:

shell> nmake -f NMakefile install

Because it uses memcached binary protocol, libcouchbase requires header files from the memcached project. After obtaining the memcached source, copy memcached.h and protocol_binary.h into c:\local\include\memcached.

Then navigate to the directory for libcouchbase. Edit the NMakefile if you wish to change the installation location, then build and install libcouchbase:

shell> nmake -f NMakefile install

Hello C Couchbase

The C client library, 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.

To connect, you must configure the connection options and then create an instance of the connection to the cluster:

struct lcb_create_st create_options;
lcb_t instance;
lcb_error_t err;

memset(&create_options, 0, sizeof(create_options));
create_options.v.v0.host = "myserver:8091";
create_options.v.v0.user = "mybucket";
create_options.v.v0.passwd = "secret";
create_options.v.v0.bucket = "mybucket";

err = lcb_create(&instance, &create_options);
if (err != LCB_SUCCESS) {
    fprintf(stderr, "Failed to create libcouchbase instance: %s\n",
            lcb_strerror(NULL, err));
    return 1;
}

/* Set up the handler to catch all errors! */
lcb_set_error_callback(instance, error_callback);

/*
 * Initiate the connect sequence in libcouchbase
 */
if ((err = lcb_connect(instance)) != LCB_SUCCESS) {
    fprintf(stderr, "Failed to initiate connect: %s\n",
            lcb_strerror(NULL, err));
    return 1;
}

/* Run the event loop and wait until we've connected */
lcb_wait(instance);

Callbacks are used by the library and are simple functions to handle the result of operations. For example:

struct lcb_create_st create_options;
lcb_t instance;
lcb_error_t err;

memset(&create_options, 0, sizeof(create_options));
create_options.v.v0.host = "myserver:8091";
create_options.v.v0.user = "mybucket";
create_options.v.v0.passwd = "secret";
create_options.v.v0.bucket = "mybucket";

err = lcb_create(&instance, &create_options);
if (err != LCB_SUCCESS) {
    fprintf(stderr, "Failed to create libcouchbase instance: %s\n",
            lcb_strerror(NULL, err));
    return 1;
}

/* Set up the handler to catch all errors! */
lcb_set_error_callback(instance, error_callback);

/*
 * Initiate the connect sequence in libcouchbase
 */
if ((err = lcb_connect(instance)) != LCB_SUCCESS) {
    fprintf(stderr, "Failed to initiate connect: %s\n",
            lcb_strerror(NULL, err));
    return 1;
}

/* Run the event loop and wait until we've connected */
lcb_wait(instance);

Callbacks can be set up for all of your operations called in libcouchbase. In the API, you’ll note the use of a “cookie”. This is opaque data from your application which is associated with the request. Underlying libcouchbase will not inspect the field, or send it to the server.

Putting the connect logic and the get callback all together into a complete program with the include headers would be:

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

static void error_callback(lcb_t instance,
                           lcb_error_t err,
                           const char *errinfo)
{
    fprintf(stderr, "Error %s: %s", lcb_strerror(instance, err),
            errinfo ? errinfo : "");
    exit(EXIT_FAILURE);
}

static void get_callback(lcb_t instance,
                         const void *cookie,
                         lcb_error_t error,
                         const lcb_get_resp_t *resp)
{
    if (error != LCB_SUCCESS) {
        fprintf(stderr, "Failed to retrieve \"");
        fwrite(resp->v.v0.key, 1, resp->v.v0.nkey, stderr);
        fprintf(stderr, "\": %s\n", lcb_strerror(instance, error));
    } else {
        fprintf(stderr, "Data for key: \"");
        fwrite(resp->v.v0.key, 1, resp->v.v0.nkey, stderr);
        fprintf(stderr, "\" is : ");
        fwrite(resp->v.v0.bytes, 1, resp->v.v0.nbytes, stderr);
    }
}

int main(void)
{
    struct lcb_create_st create_options;
    lcb_t instance;
    lcb_error_t err;

    memset(&create_options, 0, sizeof(create_options));
    create_options.v.v0.host = "myserver:8091";
    create_options.v.v0.user = "mybucket";
    create_options.v.v0.passwd = "secret";
    create_options.v.v0.bucket = "mybucket";

    err = lcb_create(&instance, &create_options);
    if (err != LCB_SUCCESS) {
        fprintf(stderr, "Failed to create libcouchbase instance: %s\n",
                lcb_strerror(NULL, err));
        return 1;
    }

    /* Set up the handler to catch all errors! */
    lcb_set_error_callback(instance, error_callback);

    /*
     * Initiate the connect sequence in libcouchbase
     */
    if ((err = lcb_connect(instance)) != LCB_SUCCESS) {
        fprintf(stderr, "Failed to initiate connect: %s\n",
                lcb_strerror(NULL, err));
        return 1;
    }

    /* Run the event loop and wait until we've connected */
    lcb_wait(instance);

    /*
     * Set up a callback for our get requests
     */
    lcb_set_get_callback(instance, get_callback);

    lcb_get_cmd_t cmd;
    const lcb_get_cmd_t * const commands[1] = { &cmd };
    memset(&cmd, 0, sizeof(cmd));
    cmd.v.v0.key = "foo";
    cmd.v.v0.nkey = 3;

    err = lcb_get(instance, NULL, 1, commands);
    if (err != LCB_SUCCESS) {
        fprintf(stderr, "Failed to get: %s\n",
                lcb_strerror(NULL, err));
        return 1;
    }

    lcb_wait(instance);

    lcb_destroy(instance);
    exit(EXIT_SUCCESS);
}

To compile this sample program, you must link to libcouchbase :

shell> gcc -o hellocb -lcouchbase hellocb.c

Tutorial

This tutorial assumes you have installed libcouchbase on your systems per the installation instructions in the Getting Started section of this guide. Because the method of building a program based on libcouchbase may vary between Linux/Mac OS and Windows, this tutorial will focus on the components of the program rather than how to build it.

If you need to set up a server node or data bucket, you can do with the Couchbase Administrative Console, or Couchbase Command-Line Interface (CLI), or the Couchbase REST API. For information and instructions, see:

After you have your Couchbase Server set up and you have installed the needed client libraries, you can compile and run the following basic program.

Simple Example

Before getting into a more complex example of the programming model to this library, we will walk through simple, straightforward example of a program which builds with libcouchbase, connects to a server, sets and gets a value:

/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
/*
 *     Copyright 2012 Couchbase, Inc.
 *
 *   Licensed under the Apache License, Version 2.0 (the "License");
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *   Unless required by applicable law or agreed to in writing, software
 *   distributed under the License is distributed on an "AS IS" BASIS,
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *   See the License for the specific language governing permissions and
 *   limitations under the License.
 */

/*
 * BUILD:
 *
 *      cc -o minimal minimal.c -lcouchbase
 *      cl /DWIN32 /Iinclude minimal.c lib\libcouchbase.lib
 *
 * RUN:
 *
 *      valgrind -v --tool=memcheck  --leak-check=full --show-reachable=yes ./minimal
 *      ./minimal <host:port> <bucket> <passwd>
 *      mininal.exe <host:port> <bucket> <passwd>
 */
#include <stdio.h>
#include <libcouchbase/couchbase.h>
#include <stdlib.h>
#include <string.h>
#include <stdint.h>
#ifdef _WIN32
#define PRIu64 "I64u"
#else
#include <inttypes.h>
#endif

static void error_callback(lcb_t instance, lcb_error_t error, const char *errinfo)
{
    fprintf(stderr, "ERROR: %s (0x%x), %s\n",
            lcb_strerror(instance, error), error, errinfo);
    exit(EXIT_FAILURE);
}

static void store_callback(lcb_t instance, const void *cookie,
                           lcb_storage_t operation,
                           lcb_error_t error,
                           const lcb_store_resp_t *item)
{
    if (error == LCB_SUCCESS) {
        fprintf(stderr, "STORED \"");
        fwrite(item->v.v0.key, sizeof(char), item->v.v0.nkey, stderr);
        fprintf(stderr, "\" CAS: %"PRIu64"\n", item->v.v0.cas);
    } else {
        fprintf(stderr, "STORE ERROR: %s (0x%x)\n",
                lcb_strerror(instance, error), error);
        exit(EXIT_FAILURE);
    }
    (void)cookie;
    (void)operation;
}

static void get_callback(lcb_t instance, const void *cookie, lcb_error_t error,
                         const lcb_get_resp_t *item)
{
    if (error == LCB_SUCCESS) {
        fprintf(stderr, "GOT \"");
        fwrite(item->v.v0.key, sizeof(char), item->v.v0.nkey, stderr);
        fprintf(stderr, "\" CAS: %"PRIu64" FLAGS:0x%x SIZE:%lu\n",
                item->v.v0.cas, item->v.v0.flags, (unsigned long)item->v.v0.nbytes);
        fwrite(item->v.v0.bytes, sizeof(char), item->v.v0.nbytes, stderr);
        fprintf(stderr, "\n");
    } else {
        fprintf(stderr, "GET ERROR: %s (0x%x)\n",
                lcb_strerror(instance, error), error);
    }
    (void)cookie;
}

int main(int argc, char *argv[])
{
    lcb_error_t err;
    lcb_t instance;
    struct lcb_create_st create_options;
    struct lcb_create_io_ops_st io_opts;

    io_opts.version = 0;
    io_opts.v.v0.type = LCB_IO_OPS_DEFAULT;
    io_opts.v.v0.cookie = NULL;

    memset(&create_options, 0, sizeof(create_options));
    err = lcb_create_io_ops(&create_options.v.v0.io, &io_opts);
    if (err != LCB_SUCCESS) {
        fprintf(stderr, "Failed to create IO instance: %s\n",
                lcb_strerror(NULL, err));
        return 1;
    }

    if (argc > 1) {
        create_options.v.v0.host = argv[1];
    }
    if (argc > 2) {
        create_options.v.v0.user = argv[2];
        create_options.v.v0.bucket = argv[2];
    }
    if (argc > 3) {
        create_options.v.v0.passwd = argv[3];
    }
    err = lcb_create(&instance, &create_options);
    if (err != LCB_SUCCESS) {
        fprintf(stderr, "Failed to create libcouchbase instance: %s\n",
                lcb_strerror(NULL, err));
        return 1;
    }
    (void)lcb_set_error_callback(instance, error_callback);
    /* Initiate the connect sequence in libcouchbase */
    if ((err = lcb_connect(instance)) != LCB_SUCCESS) {
        fprintf(stderr, "Failed to initiate connect: %s\n",
                lcb_strerror(NULL, err));
        lcb_destroy(instance);
        return 1;
    }
    (void)lcb_set_get_callback(instance, get_callback);
    (void)lcb_set_store_callback(instance, store_callback);
    /* Run the event loop and wait until we've connected */
    lcb_wait(instance);
    {
        lcb_store_cmd_t cmd;
        const lcb_store_cmd_t *commands[1];

        commands[0] = &cmd;
        memset(&cmd, 0, sizeof(cmd));
        cmd.v.v0.operation = LCB_SET;
        cmd.v.v0.key = "foo";
        cmd.v.v0.nkey = 3;
        cmd.v.v0.bytes = "bar";
        cmd.v.v0.nbytes = 3;
        err = lcb_store(instance, NULL, 1, commands);
        if (err != LCB_SUCCESS) {
            fprintf(stderr, "Failed to set: %s\n", lcb_strerror(NULL, err));
            return 1;
        }
    }
    lcb_wait(instance);
    {
        lcb_get_cmd_t cmd;
        const lcb_get_cmd_t *commands[1];
        commands[0] = &cmd;
        memset(&cmd, 0, sizeof(cmd));
        cmd.v.v0.key = "foo";
        cmd.v.v0.nkey = 3;
        err = lcb_get(instance, NULL, 1, commands);
        if (err != LCB_SUCCESS) {
            fprintf(stderr, "Failed to get: %s\n", lcb_strerror(NULL, err));
            return 1;
        }
    }
    lcb_wait(instance);
    lcb_destroy(instance);

    return 0;
}

Additional Resources

In addition to the other sections of this manual, namely the Getting Started guide and the API reference, a libcouchbase distribution includes an examples directory and a tools directory, each of which show simple Couchbase tools and and example libcouchbase programs.

On Linux you may find these examples in TODO…

API Introduction

C Method Summary

libcouchbase provides a well defined API for accessing the data stored in a Couchbase cluster. The supported methods are listed in the following tables.

API Call lcb_arithmetic (lcb_t instance, const void* cookie, const void* key, size_t nkey, int64_t delta, time_t exptime, bool create, uint64_t initial)
Asynchronous no
Description Spool an arithmetic operation to the cluster. The operation may be sent immediately, but you won’t be sure (or get the result) until you run the event loop (or call lcb_wait).
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.
const void* key An identifier in the database
size_t nkey Number of bytes in the key
int64_t delta The delta to increment/decrement
time_t exptime The expiry time for the object. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).
bool create Should the key be created if it does not exist?
uint64_t initial The initial value for the key if created
Errors
LCB_ETMPFAIL No vbucket configuration available
LCB_SUCCESS Command successfully scheduled

API Call lcb_arithmetic_by_key (lcb_t instance, const void* cookie, const void* hashkey, size_t nhashkey, const void* key, size_t nkey, int64_t delta, time_t exptime, bool create, uint64_t initial)
Asynchronous no
Description Spool an arithmetic operation to the cluster, but use another key to locate the server. The operation may be sent immediately, but you won’t be sure (or get the result) until you run the event loop (or call lcb_wait).
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.
const void* hashkey This alternate hashkey allows a client application to group a set of unique keys together to a given server though the keys themselves may be unique. For example, you may wish to use the hashkey “user” for the two data keys “user:name” and “user:birthdate”. Note that not all clients support this option so it may not be interoperable between clients.
size_t nhashkey The number of bytes in the alternative key
const void* key An identifier in the database
size_t nkey Number of bytes in the key
int64_t delta The delta to increment/decrement
time_t exptime The expiry time for the object. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).
bool create Should the key be created if it does not exist?
uint64_t initial The initial value for the key if created
Errors
LCB_ETMPFAIL No vbucket configuration available
LCB_SUCCESS Command successfully scheduled

API Call lcb_connect (lcb_t instance)
Asynchronous no
Description Initiate a connect attempt to the Couchbase cluster to get the serverlist. Please note that this method is asynchronous, so you need to call lcb_wait to wait for the method to compete.
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
Errors
LCB_NETWORK_ERROR If an IO error occurred
LCB_SUCCESS Command successfully scheduled
LCB_UNKNOWN_HOST Failed to lookup host name

API Call lcb_create (const char* host, const char* user, const char* passwd, const char* bucket, lcb_io_ops_t* iops)
Asynchronous no
Description lcb_create allocates and initializes an instance of lcb. No connection attempt is at this time. host may be specified as “host:port” and is the REST interface port for the cluster (default: “localhost:8091”). user and password are the username/password combination you want to authenticate as. bucket specifies the bucket you would like to connect to. opps is the io operation structure to use (see lcb_create_io_ops). The bucket name and the username are commonly the same.
Returns lcb_t ( The handle to the couchbase instance. )
Arguments
const char* host Hostname
const char* user Username
const char* passwd Password
const char* bucket Bucket name
lcb_io_ops_t* iops I/O operation structure
Errors
lcb_t an instance of lcb on success
NULL on failure

API Call lcb_create_io_ops ()
Asynchronous no
Description todo: fixme
Returns (none)
Arguments
None

API Call lcb_destroy (lcb_t instance)
Asynchronous no
Description lcb_destory release all allocated resources and invalidates the lcb instance.
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_disable_timings (lcb_t instance)
Asynchronous no
Description Stop recording of timing metrics and release all resources allocated for timing metrics.
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_enable_timings (lcb_t instance)
Asynchronous no
Description Start recording of timing metrics for operations against the cluster.
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_flush (lcb_t instance, const void* cookie)
Asynchronous no
Description lcb_flush may be used to remove all key/value pairs from the entire cluster.
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.
Errors
LCB_ETMPFAIL No vbucket configuration available
LCB_SUCCESS Command successfully scheduled

API Call lcb_get_cookie (lcb_t instance)
Asynchronous no
Description Each libcochbase instance may have a single pointer (cookie) associated with it. libcouchbaes_get_cookie retrieves this cookie.
Returns const void* ( Pointer to data )
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_get_last_error (lcb_t instance)
Asynchronous no
Description Returns the last error that was seen within libcoubhase
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_get_timings (lcb_t instance)
Asynchronous no
Description Retrieve the timing metrics from lcb. TODO fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_mget (lcb_t instance, const void* cookie, size_t num_keys, const void * const* keys, const size_t* nkeys, const time_t* exp)
Asynchronous no
Description Get a number of values from the cache. You need to run the event loop yourself to retrieve the data. You might want to alter the expiry time for the object you’re fetching, and to do so you should specify the new expiry time in the exp parameter. To use an ordinary mget use NULL for the exp parameter.
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.
size_t num_keys Number of keys
const void * const* keys Pointer to the array of keys
const size_t* nkeys Pointer to the array with the length of the keys
const time_t* exp Pointer to the expiry time

API Call lcb_mget_by_key (lcb_t instance, const void* cookie, const void* hashkey, size_t nhashkey, size_t num_keys, const void * const* keys, const size_t* nkeys, const time_t* exp)
Asynchronous no
Description Get a number of values from the cache. You need to run the event loop yourself (or call lcb_execute) to retrieve the data. You might want to alter the expiry time for the object you’re fetching, and to do so you should specify the new expiry time in the exp parameter. To use an ordinary mget use NULL for the exp parameter. lcb_mget_by_key differs from lcb_mget that you may use another key to look up the server to retrieve the objects from.
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.
const void* hashkey This alternate hashkey allows a client application to group a set of unique keys together to a given server though the keys themselves may be unique. For example, you may wish to use the hashkey “user” for the two data keys “user:name” and “user:birthdate”. Note that not all clients support this option so it may not be interoperable between clients.
size_t nhashkey The number of bytes in the alternative key
size_t num_keys Number of keys
const void * const* keys Pointer to the array of keys
const size_t* nkeys Pointer to the array with the length of the keys
const time_t* exp Pointer to the expiry time

API Call lcb_mtouch (lcb_t instance, const void* cookie, size_t num_keys, const void * const* keys, const size_t* nkeys, const time_t* exp)
Asynchronous no
Description Touch (set expiration time) on a number of values in the cache You need to run the event loop yourself (or call lcb_wait) to retrieve the results of the operations.
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.
size_t num_keys Number of keys
const void * const* keys Pointer to the array of keys
const size_t* nkeys Pointer to the array with the length of the keys
const time_t* exp Pointer to the expiry time

API Call lcb_mtouch_by_key (lcb_t instance, const void* cookie, const void* hashkey, size_t nhashkey, const void * const* keys, const size_t* nkeys, const time_t* exp)
Asynchronous no
Description Touch (set expiration time) on a number of values in the cache You need to run the event loop yourself (or call lcb_wait) to retrieve the results of the operations. lcb_mtouch_by_key differs from lcb_mtouch that you may use another key to look up the server for the keys.
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.
const void* hashkey This alternate hashkey allows a client application to group a set of unique keys together to a given server though the keys themselves may be unique. For example, you may wish to use the hashkey “user” for the two data keys “user:name” and “user:birthdate”. Note that not all clients support this option so it may not be interoperable between clients.
size_t nhashkey The number of bytes in the alternative key
const void * const* keys Pointer to the array of keys
const size_t* nkeys Pointer to the array with the length of the keys
const time_t* exp Pointer to the expiry time

API Call lcb_remove (lcb_t instance, const void* cookie, const void* key, size_t nkey, uint64_t cas)
Asynchronous no
Description Spool a remove operation to the cluster. The operation may be sent immediately, but you won’t be sure (or get the result) until you run the event loop (or call lcb_wait).
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.
const void* key An identifier in the database
size_t nkey Number of bytes in the key
uint64_t cas The cas value for an object is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously.

API Call lcb_remove_by_key (lcb_t instance, const void* cookie, const void* hashkey, size_t nhashkey, const void* key, size_t nkey, uint64_t cas)
Asynchronous no
Description Spool a remove operation to the cluster. The operation may be sent immediately, but you won’t be sure (or get the result) until you run the event loop (or call lcb_wait).
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.
const void* hashkey This alternate hashkey allows a client application to group a set of unique keys together to a given server though the keys themselves may be unique. For example, you may wish to use the hashkey “user” for the two data keys “user:name” and “user:birthdate”. Note that not all clients support this option so it may not be interoperable between clients.
size_t nhashkey The number of bytes in the alternative key
const void* key An identifier in the database
size_t nkey Number of bytes in the key
uint64_t cas The cas value for an object is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously.

API Call lcb_server_stats (lcb_t instance, const void* cookie, const void* key, size_t nkey)
Asynchronous no
Description Request server statistics. Without a key specified the server will respond with a “default” set of statistical information. Each statistic is returned in its own packet (key contains the name of the statistical item and the body contains the value in ASCII format). The sequence of return packets is terminated with a packet that contains no key and no value. The command will signal about transfer completion by passing NULL as the server endpoint and 0 for key length. Note that key length will be zero when some server responds with error. In the latter case server endpoint argument will indicate the server address.
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.
const void* key An identifier in the database
size_t nkey Number of bytes in the key

API Call lcb_set_arithmetic_callback (lcb_t instance, lcb_error_callback callback)
Asynchronous no
Description Specify the callback to be used for all arithmetic operations. The callback will be called whenever the operation completes, and the parameters to the callback will describe the result of the operation.
Returns ()
Arguments
lcb_t instance The handle to the couchbase instance.
lcb_error_callback callback The callback function

API Call lcb_set_cookie (lcb_t instance, const void* cookie)
Asynchronous no
Description Each libcochbase instance may have a single pointer (cookie) associated with it.
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.

API Call lcb_set_error_callback (lcb_t instance, lcb_error_callback callback)
Asynchronous no
Description Set the callback function to be used by lcb to report errors back to the client. Due to the asyncronous nature of lcb errors may occur outside of the normal access pattern and such problems will be reported through this error handler.
Returns ()
Arguments
lcb_t instance The handle to the couchbase instance.
lcb_error_callback callback The callback function

API Call lcb_set_flush_callback (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_set_get_callback (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_set_remove_callback (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_set_stat_callback (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_set_storage_callback (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_set_tap_deletion_callback (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_set_tap_flush_callback (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_set_tap_mutation_callback (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_set_tap_opaque_callback (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_set_tap_vbucket_set_callback (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_set_touch_callback (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_store (lcb_t instance, const void* cookie, lcb_storage_t store_operation, const void* key, size_t nkey, const void* bytes, size_t nbytes, flags, time_t exptime, uint64_t cas)
Asynchronous no
Description Spool a store operation to the cluster. The operation may be sent immediately, but you won’t be sure (or get the result) until you run the event loop (or call lcb_wait).
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.
lcb_storage_t store_operation The kind of storage operation (set/replace/add etc.)
const void* key An identifier in the database
size_t nkey Number of bytes in the key
const void* bytes A pointer to a memory area containing data
size_t nbytes Number of bytes used
flags
time_t exptime The expiry time for the object. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).
uint64_t cas The cas value for an object is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously.

API Call lcb_store_by_key (lcb_t instance, const void* cookie, lcb_storage_t store_operation, const void* hashkey, size_t nhashkey, const void* key, size_t nkey, const void* bytes, size_t nbytes, flags, time_t exptime, uint64_t cas)
Asynchronous no
Description Spool a store operation to the cluster. The operation may be sent immediately, but you won’t be sure (or get the result) until you run the event loop (or call lcb_wait).
Returns lcb_error_t ( lcb instance )
Arguments
lcb_t instance The handle to the couchbase instance.
const void* cookie This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it.
lcb_storage_t store_operation The kind of storage operation (set/replace/add etc.)
const void* hashkey This alternate hashkey allows a client application to group a set of unique keys together to a given server though the keys themselves may be unique. For example, you may wish to use the hashkey “user” for the two data keys “user:name” and “user:birthdate”. Note that not all clients support this option so it may not be interoperable between clients.
size_t nhashkey The number of bytes in the alternative key
const void* key An identifier in the database
size_t nkey Number of bytes in the key
const void* bytes A pointer to a memory area containing data
size_t nbytes Number of bytes used
flags
time_t exptime The expiry time for the object. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).
uint64_t cas The cas value for an object is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously.

API Call lcb_strerror (lcb_t instance)
Asynchronous no
Description Convert the error code to human readable form. @todo fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_tap_cluster (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_tap_filter_create (lcb_t instance)
Asynchronous no
Description tap filters are on the client side only, so data still needs to be transferred across the network @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_tap_filter_destroy (lcb_t instance)
Asynchronous no
Description Invalidate the filter.. @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_tap_filter_get_backfill (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_tap_filter_get_keys_only (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_tap_filter_set_backfill (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_tap_filter_set_keys_only (lcb_t instance)
Asynchronous no
Description @fixme
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

API Call lcb_wait (lcb_t instance)
Asynchronous no
Description lcb_wait cause the calling thread to block and wait until all spooled operations (and their callbacks) have completed.
Returns (none)
Arguments
lcb_t instance The handle to the couchbase instance.

View/Query Interface

Couchbase Enterprise 2.0 Server combines the speed and flexibility of Couchbase databases with the powerful JSON document database technology of CouchDB into a new product that is easy to use and provides powerful query capabilities such as map-reduce. With Couchbase Server 2.0 you are able to keep using all of the Couchbase code you already have, and upgrade certain parts of it to use JSON documents without any hassles. In doing this, you can easily add the power of Views and querying those views to your applications.

For more information on Views, how they operate, and how to write effective map/reduce queries, see Couchbase Server 2.0: Views and Couchbase Sever 2.0: Writing Views.

The libcouchbase API provides direct access to Couchbase Views, while abstracting away the details about where in the cluster the views are to be executed. It is callback oriented and allows the caller to handle data streamed back from the Couchbase cluster in HTTP chunked encoding. The entry point to the libcouchbase view API is through the libcouchbase_make_couch_request() function.

For example, to range query a view looking for all keys starting with “I” through “j”, one would execute a query similar to the following:

const char path[] = "myview?startkey=I,endkey=j";
libcouchbase_make_couch_request(instance, NULL, path, npath
                                NULL, 0, LIBCOUCHBASE_HTTP_METHOD_GET, 1);

This is derived from the libcouchbase interface:

libcouchbase_couch_request_t libcouchbase_make_couch_request(libcouchbase_t instance,
                                                                const void *command_cookie,
                                                                const char *path,
                                                                libcouchbase_size_t npath,
                                                                const void *body,
                                                                libcouchbase_size_t nbody,
                                                                libcouchbase_http_method_t method,
                                                                int chunked,
                                                                libcouchbase_error_t *error);

Where:

  • instance

    is the handle to the libcouchbase instance.

  • commandCookie

    is a cookie passed to all of the notifications from this command.

  • path

    is a literal view path with optional query parameters as specified in the Couchbase Views guide. Note that these arguments must be JSON encoded by the caller.

  • body

    is the POST body for a Couchbase viwe request. If the body argument is NULL, the function will use the GET request.

  • nbody

    is the size of the body argument.

  • method

    is the HTTP method type to be sent to the server. Most often this will be LIBCOUCHBASE_HTTPMETHOD_GET. LIBCOUCHBASE_HTTPMETHOD_PUT and LIBCOUCHBASE_HTTPMETHOD_DELETE may sometimes be used when working with design documents.

  • chunked

    if true, will configure the client to use the libcouchbas_couch_data_callback to notify the program of any responses. If it is false, the libcouchbase_couch_complete callback will be called upon completion.

  • error

    is a pointer to the error return value as defined in the interface. Additional information about the error condition may be retrieved through the libcouchbase_strerror() function.

For additional usage on this API, please refer to the examples in the source code repository at Couchbase Sever 2.0: Writing Views

Appendix: Release Notes

The following sections provide release notes for individual release versions of Couchbase Client Library C. To browse or submit new issues, see Couchbase Client Library C Issues Tracker.

Release Notes for Couchbase Client Library C 2.0.7 GA (10 July 2013)

New Features and Behavior Changes in 2.0.7

  • Improve lcb\_get\_replica(). Now it is possible to choose between three strategies:

    1. LCB_REPLICA_FIRST : Previously accessible and now the default, the caller will get a reply from the first replica to successfully reply within the timeout for the operation or will receive an error.

    2. LCB_REPLICA_ALL : Ask all replicas to send documents/items back.

    3. LCB_REPLICA_SELECT : Select one replica by the index in the configuration starting from zero. This approach can more quickly receive all possible replies for a given topology, but it can also generate false negatives.

    Note that applications should not assume the order of the replicas indicates more recent data is at a lower index number. It is up to the application to determine which version of a document/item it may wish to use in the case of retrieving data from a replica.

    Issues : CCBC-183

Release Notes for Couchbase Client Library C 2.0.6 GA (07 May 2013)

New Features and Behavior Changes in 2.0.6

Fixes in 2.0.6

  • Fix segfault when rebalancing. When a (!connected) server is reconnected, the tasks in its “pending” buffer will be moved into “output” buffer. If its connection is broken again immediately, relocate_packets() will go to wrong path.

    Issues : CCBC-188

  • Don’t try to switch to backup nodes when timeout is reached

    Issues : CCBC-202

  • Fix compile error with sun studio. "src/event.c", line 172: error: statement not reached (E_STATEMENT_NOT_REACHED)

  • Don’t invoke HTTP callbacks after cancellation, because user code might assume a previously-freed resource is still valid

  • Check if SASL struct is valid before disposing

    Issues : CCBC-188

  • example/yajl/couchview.c: pass cookie to the command Fixes coredump when executing./examples/yajl/couchview

Release Notes for Couchbase Client Library C 2.0.5 GA (05 April 2013)

New Features and Behavior Changes in 2.0.5

  • pillowfight example updated to optionally use threads

Fixes in 2.0.5

Release Notes for Couchbase Client Library C 2.0.4 GA (06 March 2013)

Fixes in 2.0.4

  • Build error on solaris/sparc: -Werror=cast-align

    Issues : CCBC-178

  • Fixed illegal memory access in win32 plugin

    Issues : CCBC-147

  • Work properly on systems where EWOULDBLOCK != EAGAIN

    Issues : CCBC-175

  • The library stops iterating backup nodes list if the next one isn’t accessible.

    Issues : CCBC-182

  • The bootstrap URI is not parsed correctly

    Issues : CCBC-185

  • Segmentation fault when the hostname resolved into several addresses and first of them reject couchbase connections.

    Issues : CCBC-180

Release Notes for Couchbase Client Library C 2.0.3 GA (06 February 2013)

New Features and Behavior Changes in 2.0.3

  • Add a new library: libcouchbase_debug.so (see include/libcouchbase/debug.h) which is a new library that contains new debug functionality.

  • Added manual pages for the library.

Fixes in 2.0.3

  • Observe malfunctions in the case of multiple keys and server failure.

    Issues : CCBC-155

  • Reset internal state on lcb_connect(). Allow caller to use lcb_connect() multiple times to implement reconnecting using the same lcb_t instance. Also it sets up the initial-connection timer for users who don’t use lcb_wait() and drive IO loop manually.

    Issues : CCBC-153

  • Invalid read in libevent plugin, when the plugin compiled in 1.x mode

    Issues : CCBC-171

  • Shrink internal lookup tables (and reduce the size of lcb_t)

  • Issues : CCBC-156

Release Notes for Couchbase Client Library C 2.0.2 GA (04 January 2013)

Fixes in 2.0.2

  • Document LCB_SERVER_BUG and LCB_PLUGIN_VERSION_MISMATCH. Enhance the lcb_strerror test to detect undocumented error codes.

  • Commands sent to multiple servers fail to detect the respose if mixed with other commands.

    Issues : CCBC-150

  • Under high load the library could generate LCB_ETIMEDOUT errors without reason owing to internal limitations.

    Issues : CCBC-153

  • Cancellation of the HTTP request might lead to memory leaks or to segfaults (2e3875c2).

    Issues : CCBC-151

Release Notes for Couchbase Client Library C 2.0.1 GA (11 December 2012)

New Features and Behavior Changes in 2.0.1

  • SystemTap and DTrace integration

Fixes in 2.0.1

  • Fix a memory leak on the use of http headers

    Issues : CCBC-130

  • libev-plugin: delay all timers while the loop isn’t active. It will fix LCB_ETIMEOUT in the following scenario:

    • connect the instance

    • sleep for time greater than default timeout (e.g. 3 seconds)

    • schedule and execute a command (it will be timed out immediately)

  • Do not abort when purging SASL commands

    Issues : CCBC-136

  • Fix possible SEGFAULT. Not-periodic timers are destroyed after calling user’s callback, after that library performed read from freed pointer.

  • Compensate for cluster nodes lacking couchApiBase

    Issues : CCBC-131

  • Ensure HTTP works even when the network may be unreliable. This changeset encompasses several issues which had been found with HTTP requests during network errors and configuration changes. Specifically some duplicate code paths were removed, and the process for delivering an HTTP response back to the user is more streamlined.

    Issues : CCBC-132, CCBC-133

  • libev-plugin: reset IO event on delete. We need to reset it, because it might be re-used later

  • Make library C89 friendly again

Release Notes for Couchbase Client Library C 2.0.0 GA (27 November 2012)

New Features and Behavior Changes in 2.0.0

  • Add the CAS to the delete callback

Fixes in 2.0.0

  • Minor update of the packaging layout:

    • libcouchbase-all package comes without version

    • extract debug symbols from libcouchbase-{bin,core} to libcouchbase-dbg package

  • Install unlock callback in synchronous mode

Release Notes for Couchbase Client Library C 2.0.0beta3 Beta (21 November 2012)

New Features and Behavior Changes in 2.0.0beta3

  • Try all known plugins for LCB_IO_OPS_DEFAULT in run time

  • Allow to use ‘cbc-hash’ with files

  • Create man pages for cbc and cbcrc

  • Use dynamic versioning for plugins

  • Lookup the plugin symbol also in the current executable image.

    Issues : CCBC-114

  • Allow the user to specify a different hash key. All of the data operations contains a hashkey and nhashkey field. This allows you to “group” items together in your cluster. A typical use case for this is if you’re storing lets say data for a single user in multiple objects. If you want to ensure that either all or none of the objects are available if a server goes down, it could be a good idea to locate them on the same server. Do bear in mind that if you do try to decide where objects is located, you may end up with an uneven distribution of the number of items on each node. This will again result in some nodes being more busy than others etc. This is why some clients doesn’t allow you to do this, so bear in mind that by doing so you might not be able to get your objects from other clients.

    Issues : CCBC-119

  • Add documentation about the error codes

    Issues : CCBC-87

  • Add lcb_verify_compiler_setup(). This function allows the “user” of the library to verify that the compiler use a compatible struct packing scheme.

Fixes in 2.0.0beta3

  • lcb_error_t member in the http callbacks shouldn’t reflect the HTTP response code. So the error code will be always LCB_SUCCESS if the library managed to receive the data successfully.

    Issues : CCBC-118

  • Fix cbc-bucket-create. `sasl-password' is misspelled, and it fails to parse the command line option.

  • Remove libtool version from the plugins

  • Do not allow admin operations without authentication

  • check for ewouldblock/eintr on failed send

  • Purge stale OBSERVE packets

    Issues : CCBC-120

  • Allow to use gethrtime() from C++

  • Remove unauthorized asserion (d344037). The lcb_server_send_packets() function later check if the server object connected and establish connection if not (with raising possible errors)

    Issues : CCBC-113

  • Don’t use the time_t for win32. When compiling from php it turns out that it gets another size of the time_t type, causing the struct offsets to differ.

  • Reformat and refactor lcb_server_purge_implicit_responses:

    • move packet allocation out of GET handler

    • dropping NOOP command shouldn’t return error code

    Issues : CCBC-120

  • Try to switch another server from backup list on timeout

    Issues : CCBC-122

  • Timer in libev uses double for interval. Ref: http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_timer_code_relative_and_opti

  • Fix illegal memory access. Reconnect config listener if the config connection was gone without proper shutdown.

    Issues : CCBC-104

  • Fix using freed memory (was introduced in 4397181)

  • Return zero from do_read_data() if operations_per_call reached. The `operations_per_call' limit was introduced to prevent from freezing event loop. But in the function variable rv could store two different results and in case of reaching this limit it is returning number of the processed records, which is wrong. The function should return either zero (success) or non-zero (failure).

    Issues : CCBC-115

Release Notes for Couchbase Client Library C 2.0.0beta2 Beta (12 October 2012)

New Features and Behavior Changes in 2.0.0beta2

  • Implement a new libev plugin. It is compatible with both libev3 and libev4.

  • Allow libcouchbase to connect to an instance without specifying bucket. It is useful when the bucket not needed, e.g. when performing administration tasks.

  • Allow users to build the library without dependencies. For example, without plugins at all. This may be useful if the plugin is implemented by or built into the host application.

  • Allow users to use environment variables to pick the event plugin

  • Add a new interface version for creating IO objects via plugins

  • Allow to disable CXX targets

  • Allow users to install both libraries (2.x and 1.x) on the same system.

  • Cleanup HTTP callbacks. Use the same callbacks both for Management and View commands, and rename them to lcb_http_complete_callback and lcb_http_data_callback.

  • Add support for raw http requests. libcouchase already contains all the bits to execute a raw http request, except for the possibility to specify a host:port, username and password.

  • Make the content type optional for lcb_make_http_request()

Fixes in 2.0.0beta2

  • Fix invalid memory access in cbc tool. Affected command is cbc-bucket-create

  • Search ev.h also in ${includedir}/libev

  • Fix password memory leak in http.c (7e71493)

  • lcb_create: replace assert() with error code

  • Breakout event loop in default error_callback. This provides better default behavior for users who haven’t defined global error callback.

    Issues : CCBC-105

  • Fix linked event/timer lists for win32

    Issues : CCBC-103

  • Fix SEGFAULT if IO struct is allocated not by the lcb_create()

  • Fix memory leak after an unsuccessful connection

  • lcb_connect() should honor the syncmode setting. Automatically call lcb_wait() when in synchronous mode

Release Notes for Couchbase Client Library C 2.0.0beta Beta (13 September 2012)

New Features and Behavior Changes in 2.0.0beta

  • Bundle Windows packages as zip archives

  • Refactor the API. This is a full redesign of the current libcouchbase API that’ll allow us to extend parts of the API without breaking binary compatibility. Also it renames all functions to have lcb prefix instead of libcouchbase and LCB/LIBCOUCHBASE in macros.

  • Implement getter for number of nodes in the cluster: lcb_get_num_nodes()

  • Add lcb_get_server_list() to get current server list

  • Deliver HTTP headers via callbacks

  • Implement RESTful flush in the cbc toolset

  • Merge lcb_get_locked into lcb_get function

  • Bundle libvbucket

Fixes in 2.0.0beta

  • Fix a problem with allocating too few slots in the backup_nodes. Fixes illegal memory access.

  • Include sys/uio.h. Needed by OpenBSD

  • Added --enable-fat-binary. Helps to solve issues when linking with fat binaries on MacOS.

  • Differentiate between TMPFAILs. This allows a developer to know if the temporary condition where the request cannot be handled is due to a constraint on the client or the server.

    Issues : CCBC-98

  • Correct buffer length for POST/PUT headers

    Issues : CCBC-96

  • Fix switching to backup node in case of server outage

    Issues : CCBC-91

  • Fix locking keys in multi-get mode

  • Release the memory allocated by the http parser

    Issues : CCBC-89

  • Fix initialization of backup nodes array. The code switching nodes relies on NULL terminator rather than nbackup_nodes variable. Fixes illegal memory access.

    Issues : CCBC-90

  • Default to IPv4 only

    Issues : CCBC-80

  • Reset timer for commands with NOT_MY_VBUCKET response

    Issues : CCBC-91

  • Sync memcached/protocol_binary.h. Pull extra protocol_binary_datatypes declarations.

  • Fix bug where HTTP method is not set

  • Don’t try to put the current node last in the backup list. This may cause “duplicates” in the list if the REST server returns another name for the server than you used. Ex: you specify “localhost” and the REST response contains 127.0.0.1

  • Release ringbuffer in lcb_purge_single_server

    Issues : CCBC-92

Release Notes for Couchbase Client Library C 1.1.0dp9 Developer Preview (27 July 2012)

Fixes in 1.1.0dp9

  • Render auth credentials for View requests. libcouchbase_make_http_request() won’t accept credentials anymore. It will pick them bucket configuration.

Release Notes for Couchbase Client Library C 1.1.0dp8 Developer Preview (27 July 2012)

New Features and Behavior Changes in 1.1.0dp8

  • Allow the user to get the number of replicas using libcouchbase_get_num_replicas()

  • Separate HTTP callbacks for couch and management requests

  • Implement read replica

    Issues : CCBC-82

  • Let users detect if the event loop running already using libcouchbase_is_waiting() function.

  • Add OBSERVE command

    Issues : CCBC-15

  • Allow users to specify content type for HTTP request.

  • Allow a user to breakout from the event loop in callbacks using libcouchbase_breakout()

  • New cbc commands and options:

    • cbc-view (remove couchview example)

    • cbc-verbosity

    • cbc-admin

    • cbc-bucket-delete

    • cbc-bucket-create

    • Add -p and -r options to cbc-cp to control persistence (uses OBSERVE internally)

  • Allow the client to specify the verbosity level on the servers using lcb_set_verbosity() function.

  • Implement general purpose timers. It is possible for users to define their own timers using libcouchbase_timer_create() function. (See headers for more info). Implement multiple timers for windows

    Issues : CCBC-85

Fixes in 1.1.0dp8

  • Claim that server has data in buffers if there are HTTP requests pending. Without this patch the event loop can be stopped prematurely.

  • Make libcouchbase_wait() re-entrable

  • Fix to handle the case when View base doesn’t have URI schema.

  • Bind timeouts to server sockets instead of commands. This means that from this point timeout interval will be started from the latest IO activity on the socket. This is a behavior change from the 1.0 series.

  • Use separate error code for ENOMEM on the client

    Issues : CCBC-77

Release Notes for Couchbase Client Library C 1.1.0dp7 Developer Preview (19 June 2012)

New Features and Behavior Changes in 1.1.0dp7

  • Implement function to execution management requests. Using libcouchbase_make_management_request() function you can configure the cluster, add/remove buckets, rebalance etc. It behaves like libcouchbase_make_couch_request() but works with another endpoint.

  • Add support for notification callbacks for configuration changes. Now it is possible to install a hook using function libcouchbase_set_configuration_callback(), and be notified about all configuration changes.

Fixes in 1.1.0dp7

  • Extract HTTP client. Backward incompatible change in Couchbase View subsystem

Release Notes for Couchbase Client Library C 1.1.0dp6 Developer Preview (13 June 2012)

New Features and Behavior Changes in 1.1.0dp6

  • Implement ‘help’ command for cbc tool

    Issues : RCBC-71

Fixes in 1.1.0dp6

  • Undefine NDEBUG to avoid asserts to be optimized out

  • Fix compilation on macosx with gtest from homebrew

    Issues : RCBC-72

  • Close dynamic libraries. Fixes small memory leak

    Issues : RCBC-70

  • Include types definitions for POSIX systems. Fixes C++ builds on some systems.

    Issues : RCBC-63

  • Fix win32 builds:

    • Add suffix to cbc command implementations;

    • Fix guards for socket errno macros;

    • Define size_t types to fix MSVC 9 build;

    • MSVC 9 isn’t C99, but has stddef.h, so just include it.

Release Notes for Couchbase Client Library C 1.1.0dp5 Developer Preview (06 June 2012)

New Features and Behavior Changes in 1.1.0dp5

  • Implement ‘cbc-hash’ to get server/vbucket for given key

Fixes in 1.1.0dp5

  • The library doesn’t depend on pthreads (eliminates package lint warnings)

Release Notes for Couchbase Client Library C 1.1.0dp4 Developer Preview (05 June 2012)

Fixes in 1.1.0dp4

  • cbc: strtoull doesn’t exist on win32, therefore use C++ equivalent.

Release Notes for Couchbase Client Library C 1.1.0dp3 Developer Preview (03 June 2012)

New Features and Behavior Changes in 1.1.0dp3

  • Implement GET_LOCKED (GETL) command

    Issues : CCBC-68

  • Implement UNLOCK_KEY (UNL) command

    Issues : CCBC-68

Fixes in 1.1.0dp3

  • Timeouts can occur during topology changes, rather than be correctly retried. Send the retry-packet to new server

    Issues : CCBC-64

  • Fix ringbuffer_memcpy() (36afdb2). Fix ringbuffer_is_continous().

  • A hang could occur in libcouchbase_wait() after the timeout period. Check for breakout condition after purging servers

    Issues : CCBC-62

  • Destroy view requests items when server get destroyed. Fixes memory leaks.

  • A fix for a buffer overflow with the supplied password as has been integrated. While it is a buffer overflow issue, this is not considered to be a possible security issue because the password to the bucket is not commonly supplied by an untrusted source

    Issues : RCBC-33

  • A small memory leak can occur with frequent calls to libcouchbase_create() and libcouchbase_destroy()

    Issues : CCBC-65

  • Use vbucket_found_incorrect_master() to get correct server index during relocating buffers. Pick up cookies from pending buffer unless node connected.

  • Do not call View callbacks for cancelled requests

  • hashset.c: iterate over whole set on rehashing. Fixes memory leaks related to hash collisions (905ef95)

Release Notes for Couchbase Client Library C 1.1.0dp2 Developer Preview (10 April 2012)

Fixes in 1.1.0dp2

  • Don’t wait for empty buffers. If called with no operations queued, libcouchbase_wait() will block forever. This means that a single threaded application that calls libcouchbase_wait() at different times to make sure operations are sent to the server runs the risk of stalling indefinitely. This is a very likely scenario.

    Issues : CCBC-59

  • Don’t define size_t and ssize_t for VS2008

  • Fix segfault while authorizing on protected buckets (211bb04)

Release Notes for Couchbase Client Library C 1.1.0dp Developer Preview (05 April 2012)

New Features and Behavior Changes in 1.1.0dp

  • This release adds new functionality to directly access Couchbase Server views using the libcouchbase_make_couch_request() function. See the associated documentation and header files for more details.

Fixes in 1.1.0dp

  • Request the tap bytes in a known byte order (adf2b30)

    Issues : MB-4834

  • Check for newer libvbucket

Appendix: Licenses

This documentation and associated software is subject to the following licenses.

Documentation License

This documentation in any form, software or printed matter, contains proprietary information that is the exclusive property of Couchbase. Your access to and use of this material is subject to the terms and conditions of your Couchbase Software License and Service Agreement, which has been executed and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Couchbase without prior written consent of Couchbase or as specifically provided below. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Couchbase or its subsidiaries or affiliates.

Use of this documentation is subject to the following terms:

You may create a printed copy of this documentation solely for your own personal use. Conversion to other formats is allowed as long as the actual content is not altered or edited in any way. You shall not publish or distribute this documentation in any form or on any media, except if you distribute the documentation in a manner similar to how Couchbase disseminates it (that is, electronically for download on a Web site with the software) or on a CD-ROM or similar medium, provided however that the documentation is disseminated together with the software on the same medium. Any other use, such as any dissemination of printed copies or use of this documentation, in whole or in part, in another publication, requires the prior written consent from an authorized representative of Couchbase. Couchbase and/or its affiliates reserve any and all rights to this documentation not expressly granted above.

This documentation may provide access to or information on content, products, and services from third parties. Couchbase Inc. and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Couchbase Inc. and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

The information contained herein is subject to change without notice and is not warranted to be error free. If you find any errors, please report them to us in writing.