Couchbase C Client  2.7.7

Detailed Description

To communicate with a Couchbase cluster, a new library handle instance is created in the form of an lcb_t. To create such an object, the lcb_create() function is called, passing it a structure of type lcb_create_st. The structure acts as a container for a union of other structures which are extended as more features are added. This container is forwards and backwards compatible, meaning that if the structure is extended, you code and application will still function if using an older version of the structure. The current sub-field of the lcb_create_st structure is the v3 field.

Connecting to the cluster involes the client knowing the necessary information needed to actually locate its services and connect to it.

A connection specification consists of:

  1. One or more hosts which comprise the cluster
  2. The name of the bucket to access and perform operations on
  3. The credentials of the bucket

All these options are specified within the form of a URI in the form of


If any of the fields (hosts, bucket, options) contain the / character then it must be url-encoded; thus a bucket named foo/bar would be specified as couchbase:///foo%2Fbar

In the most typical use case, you would specify a list of several hostnames delimited by a comma (,); each host specified should be a member of the cluster. The library will use this list to initially connect to the cluster.

Note that it is not necessary to specify all the nodes of the cluster as in a normal situation the library will only initially connect to one of the nodes. Passing multiple nodes increases the chance of a connection succeeding even if some of the nodes are currently down. Once connected to the cluster, the client will update itself with the other nodes actually found within the cluster and discard the list passed to it

You can specify multiple hosts like so:


Or a single host:


Specifying Ports and Protocol Options

The default couchbase:// scheme will assume all hosts and/or ports specify the memcached port. If no port is specified, it is assumed that the port is _11210). For more extended options there are additional schemes available:


A bucket may be specified by using the optional path component of the URI For protected buckets a password will still need to be supplied out of band.


The key-value options here are considered to be a volatile interface as their names may change.

Options can be specified as the query part of the connection string, for example:


Options may either be appropriate key parameters for lcb_cntl_string() or one of the following:

Bucket Identification and Credentials

The most common settings you will wish to modify are the bucket name and the credentials field (user and passwd). If a bucket is not specified it will revert to the default bucket (i.e. the bucket which is created when Couchbase Server is installed).

The user and passwd fields authenticate for the bucket. This is only needed if you have configured your bucket to employ SASL auth. You can tell if the bucket has been configured with SASL auth by

  1. Logging into the Couchbase Administration Console
  2. Going to the Data Buckets tab
  3. Locate the row for your bucket
  4. Expand the row into the detailed view (by clicking on the arrow at the left of the row)
  5. Click on Edit
  6. Inspect the Access Control section in the pop-up

The bucket name is specified as the path portion of the URI.

For security purposes, the user and passwd cannot be specified within the URI

You may not change the bucket or credentials after initializing the handle.

Bootstrap Options

The default configuration process will attempt to bootstrap first from the new memcached configuration protocol (CCCP) and if that fails, use the "HTTP" protocol via the REST API.

The CCCP configuration will by default attempt to connect to one of the nodes specified on the port 11201. While normally the memcached port is determined by the configuration itself, this is not possible when the configuration has not been attained. You may specify a list of alternate memcached servers by using the 'mchosts' field.

If you wish to modify the default bootstrap protocol selection, you can use the bootstrap_on option to specify the desired bootstrap specification to use for configuration (note that the ordering of this array is ignored). Using this mechanism, you can disable CCCP or HTTP.

To force only "new-style" bootstrap, you may use bootstrap_on=cccp. To force only "old-style" bootstrap, use bootstrap_on=http. To force the default behavior, use bootstrap_on=all


lcb_error_t lcb_create (lcb_t *instance, const struct lcb_create_st *options)
 Create an instance of lcb. More...
lcb_error_t lcb_connect (lcb_t instance)
 Schedule the initial connection This function will schedule the initial connection for the handle. More...
lcb_bootstrap_callback lcb_set_bootstrap_callback (lcb_t instance, lcb_bootstrap_callback callback)
 Set the callback for notification of success or failure of initial connection. More...
lcb_error_t lcb_get_bootstrap_status (lcb_t instance)
 Gets the initial bootstrap status. More...
void lcb_set_auth (lcb_t instance, lcb_AUTHENTICATOR *auth)
 Sets the authenticator object for the instance. More...


typedef struct lcb_st * lcb_t
 Library handle representing a connection to a data bucket. More...
typedef void(* lcb_bootstrap_callback) (lcb_t instance, lcb_error_t err)
 Bootstrap callback. More...


enum  lcb_type_t
 Handle types. More...
enum  lcb_BTYPE
 Type of the bucket. More...

Function Documentation

◆ lcb_create()

lcb_error_t lcb_create ( lcb_t instance,
const struct lcb_create_st options 

Create an instance of lcb.

instanceWhere the instance should be returned
optionsHow to create the libcouchbase instance
LCB_SUCCESS on success


Create an instance using the default values:

lcb_t instance;
lcb_error_t err = lcb_create(&instance, NULL);
if (err != LCB_SUCCESS) {
fprintf(stderr, "Failed to create instance: %s\n", lcb_strerror(NULL, err));

Specify server list

struct lcb_create_st options;
memset(&options, 0, sizeof(options));
options.version = 3;
options.v.v3.connstr = "couchbase://host1,host2,host3";
err = lcb_create(&instance, &options);

Create a handle for data requests to protected bucket

struct lcb_create_st options;
memset(&options, 0, sizeof(options));
options.version = 3; = "couchbase://,"
options.v.v3.passwd = "secret";
err = lcb_create(&instance, &options);
See also
example/libeventdirect/main.c, and example/minimal/minimal.c.

◆ lcb_connect()

lcb_error_t lcb_connect ( lcb_t  instance)

Schedule the initial connection This function will schedule the initial connection for the handle.

This function must be called before any operations can be performed.

lcb_set_bootstrap_callback() or lcb_get_bootstrap_status() can be used to determine if the scheduled connection completed successfully.

Synchronous Usage
lcb_error_t rc = lcb_connect(instance);
if (rc != LCB_SUCCESS) {
rc = lcb_get_bootstrap_status(instance);
if (rc != LCB_SUCCESS) {
example/libeventdirect/main.c, and example/minimal/minimal.c.

◆ lcb_set_bootstrap_callback()

lcb_bootstrap_callback lcb_set_bootstrap_callback ( lcb_t  instance,
lcb_bootstrap_callback  callback 

Set the callback for notification of success or failure of initial connection.

instancethe instance
callbackthe callback to set. If NULL, return the existing callback
The existing (and previous) callback.
See also

◆ lcb_get_bootstrap_status()

lcb_error_t lcb_get_bootstrap_status ( lcb_t  instance)

Gets the initial bootstrap status.

This is an alternative to using the lcb_bootstrap_callback() and may be used after the initial lcb_connect() and lcb_wait() sequence.

LCB_SUCCESS if properly bootstrapped or an error code otherwise.
Calling this function only makes sense during instantiation.

◆ lcb_set_auth()

void lcb_set_auth ( lcb_t  instance,

Sets the authenticator object for the instance.

This may be done anytime, but should probably be done before calling lcb_connect() for best effect.

instancethe handle
auththe authenticator object used. The library will increase the refcount on the authenticator object.

Data Structure Documentation

◆ lcb_create_st3

struct lcb_create_st3

Innser structure for lcb_create().

Data Fields

const char * connstr
 Connection string.
const char * username
 Username to use for authentication. More...
const char * passwd
 Password for bucket. More...
struct lcb_io_opt_st * io
 IO Options.
lcb_type_t type

Field Documentation

◆ username

const char* username

Username to use for authentication.

This should only be set when connecting to a server 5.0 or greater.

◆ passwd

const char* passwd

Password for bucket.

Can also be password for username on servers >= 5.0


◆ lcb_create_st

struct lcb_create_st
Data Fields
int version Indicates which field in the lcb_CRST_u union should be used.

Set this to 3

union lcb_CRST_u v

Typedef Documentation

◆ lcb_t

typedef struct lcb_st* lcb_t

Library handle representing a connection to a data bucket.

The contents of this structure are opaque.

See also

◆ lcb_bootstrap_callback

typedef void(* lcb_bootstrap_callback) (lcb_t instance, lcb_error_t err)

Bootstrap callback.

Invoked once the instance is ready to perform operations

instanceThe instance which was bootstrapped
errThe error code received. If this is not LCB_SUCCESS then the instance is not bootstrapped and must be recreated
This callback only receives information during instantiation.

Enumeration Type Documentation

◆ lcb_type_t

enum lcb_type_t

Handle types.

See also

Handle for data access (default)


Handle for administrative access.

◆ lcb_BTYPE

enum lcb_BTYPE

Type of the bucket.

See also

Unknown or unspecified.


Data persisted and replicated.


Data not persisted, but replicated.


Data not persisted and not replicated.