Install and Start Using the C (libcouchbase) SDK with Couchbase Server

The Couchbase C SDK (libcouchbase) enables C and C++ programs to access a Couchbase cluster.
The C SDK is also commonly used as a core dependency of SDKs written in other language to provide a common implementation and high performance.

Features

Cross-Platform: Officially supported on Linux, Mac OS X, and Microsoft Windows (though it is also known to run on other platforms).

Key-Value (CRUD) operations (lcb_get3, lcb_store3, etc.)

N1QL query operations (lcb_n1ql_query)

Map Reduce (view) query operations (lcb_view_query)

Secure SSL connections (Couchbase Enterprise only)

Pluggable non-blocking event loops such as libevent, libev, and libuv- integrate with your own non-blocking application, or use lcb_wait in blocking code

Note that SSL and N1QL features depend on server support.
See Compatibility to see which server versions support which features.

Installing on Linux

For installation on Linux, install the couchbase-release repository, and then install the libcouchbase packages.
The following examples download and install couchbase-release repository, a C and C++ compiler, and the C SDK core (libcouchbase2-core), command line tools (libcouchbase2-bin), and the development tools (libcouchbase-devel [RPM] or libcouchbase-dev [DEB]).

Note that as of Couchbase Data Platform 6.0, couchbase-release (1.0.4) supports Debian 7 and 8, and Ubuntu 12.04, 14.04, and 16.04. If you wish to install a Couchbase SDK on a more recent Ubuntu or Debian, follow these steps (but note that beyond Ubuntu 18.04, other platforms are not necessarily supported):

You should install the libcouchbase2-libevent or libcouchbase2-libev plugin in case your application will use more than 1024 file descriptors.
The default select() based event loop only supports 1024 file descriptors.

Installation on Mac OS X

To install the library on Mac OS X, first install the de-facto package manager for OS X: homebrew.
Once homebrew is configured:

brew update # get list of latest packages
brew install libcouchbase

Installation on Microsoft Windows

Installing from Source Code

You may install the library from source code, either via a repository checkout or using a release tarball (download links may be found at Installation and Release Notes.
Follow the instructions in the README.markdown file at the top of the source tree.

Documentation and Examples

A reference guide (this manual) is suitable for a general overview and learning how to use the library.

The API documentation is generated from comments in the header and covers all the APIs of the library.

Information on new features, fixes, known issues as well as information on how to install older release versions is available in the release notes.

Hello Couchbase

The simple example below (which requires version 2.5.6 or higher to function) can be integrated into an existing application, or added to a CLI skeleton to make a demo app.
Error checking is omitted for brevity.

Scheduling, Blocking and non-blocking

The library is designed to be non-blocking.
As opposed to a blocking API where API calls themselves perform the operations and return results, the C SDK’s non-blocking API schedules the operation, with the result of the operation being passed to a callback which is invoked when ready.
The readiness and completion of an operation will only happen when the library has had a chance to send the operation to the server and await a response from the network.

Most operations in the library do not execute the operation immediately, but rather schedule it to be executed when it is possible to perform network I/O.

The lcb_wait() function will instruct the library to send all scheduled operations to the cluster and await the results for those operations.
As results become available, designated callbacks (specified using lcb_install_callback3()) are invoked with the results.

If your application is built on top of an event loop (for example, libev) you can integrate the C SDK to perform its I/O within the context of your event loop, avoiding the need to block for I/O with lcb_wait().

Library Handle and Server Connections

Almost all operations within the library are done with a library handle of type lcb_t.
The lcb_t is a handle representing a connection to a single bucket (though it is possible to access other buckets as well for certain operations).

An lcb_t is created using the lcb_create() function.
Once created the handle must be connected: lcb_connect() schedules the connection and lcb_wait waits for the connection to complete.
Once lcb_wait returns, lcb_get_bootstrap_status may be used to determine if the connection completed successfully.

Once the handle has been successfully connected it may then be used for data access.

When the library handle is no longer needed, it can be destroyed via lcb_destroy().