A newer version of this software is available
You are viewing the documentation for an older version of this software. To find the documentation for the current version, visit the Couchbase documentation home page.
This guide provides information for developers who want to use the Couchbase C SDK to build applications that use Couchbase Server.
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.
Download the latest client library from the Couchbase download
site. It is available as a source
archive in both .zip
and .tar.gz
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:
You must seed RPM with a new source, which is depedendent on your RedHat version:
RHEL/CentOS 5.5
shell> sudo wget -O/etc/yum.repos.d/couchbase.repo \
http://packages.couchbase.com/rpm/couchbase-centos55-i386.repo
shell> sudo wget -O/etc/yum.repos.d/couchbase.repo \
http://packages.couchbase.com/rpm/couchbase-centos55-x86_64.repo
RHEL/CentOS 6.2
shell> sudo wget -O/etc/yum.repos.d/couchbase.repo \
http://packages.couchbase.com/rpm/couchbase-centos62-i686.repo
shell> sudo wget -O/etc/yum.repos.d/couchbase.repo \
http://packages.couchbase.com/rpm/couchbase-centos62-x86_64.repo
Then to install libcouchbase itself, run:
shell> sudo yum check-update
shell> sudo yum install -y libcouchbase2 libcouchbase-devel
You must update the apt-get
repository:
Ubuntu 12.04 Precise Pangolin (Debian unstable)
Also compatible with recent versions, which have libevent2
.
shell> sudo wget -O/etc/apt/sources.list.d/couchbase.list \
http://packages.couchbase.com/ubuntu/couchbase-ubuntu1204.list
Ubuntu 11.10 Oneiric Ocelot (Debian unstable)
Also compatible with recent versions, which have libevent2
.
shell> sudo wget -O/etc/apt/sources.list.d/couchbase.list \
http://packages.couchbase.com/ubuntu/couchbase-ubuntu1110.list
Ubuntu 10.04 Lucid Lynx (Debian stable or testing)
shell> sudo wget -O/etc/apt/sources.list.d/couchbase.list \
http://packages.couchbase.com/ubuntu/couchbase-ubuntu1004.list
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
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
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.
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
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
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:
Using the Couchbase Web Console, for information on using the Couchbase Administrative Console,
Couchbase CLI, for the command line interface,
Couchbase REST API, for creating and managing Couchbase resources.
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.
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;
}
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…
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. |
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
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.
New Features and Behavior Changes in 2.0.7
Improve lcb\_get\_replica()
. Now it is possible to choose between three
strategies:
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.
LCB_REPLICA_ALL
: Ask all replicas to send documents/items back.
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
New Features and Behavior Changes in 2.0.6
Added an example to properly use the bucket credentials for authentication instead of administrator credentials
Issues : CCBC-179
Add Host header in http request http://cbugg.hq.couchbase.com/bug/bug-555 points out that Host is a required field in HTTP 1.1
Issues : CCBC-201
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
New Features and Behavior Changes in 2.0.5
Fixes in 2.0.5
Try to search the –libdir for modules if dlopen fails to find the module in the default library path
New compat mode (experimental) for configuration caching. See man lcb_create_compat
Issues : CCBC-190
Fix reconnecting issues on windows (http://review.couchbase.org/25170 and http://review.couchbase.org/25155)
Fix build on FreeBSD (http://review.couchbase.org/25289)
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
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
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
New Features and Behavior Changes in 2.0.1
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.
libev-plugin: reset IO event on delete. We need to reset it, because it might be re-used later
Make library C89 friendly again
New Features and Behavior Changes in 2.0.0
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
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
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
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
Fixes in 1.1.0dp9
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
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
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.
New Features and Behavior Changes in 1.1.0dp5
Fixes in 1.1.0dp5
Fixes in 1.1.0dp4
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)
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)
New Features and Behavior Changes in 1.1.0dp
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