Couchbase C SDK Release Notes and Download Archives

Installation

You can install the C SDK from a repository for your platform, download prebuilt binaries, or compile from source.

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

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.6) supports Debian 7, 8, and 9, and Ubuntu 12.04, 14.04, 16.04, and 18.04. If you wish to install a Couchbase SDK on another Ubuntu or Debian variation, follow these steps (but note that while newer releases may work, 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.

Installing Manually - Linux

If you want to install the C SDK manually, either from a static binary package or by manually configuring the repositories, you can use the following procedures.

The various Linux distributions contain the following packages:

libcouchbase2-core: The core library package.

libcouchbase-dev (or libcouchbase-devel): The development package, required if building SDKs which depend on the C SDK.

libcouchbase2-bin: The command line utilities (cbc and cbc-pillowfight).

libcouchbase2-libevent: Optional but recommended component for I/O performance. Can also be used to integrate with libevent (see Asynchronous Programming).

libcouchbase2-libev: Optional, for use with applications that make use of event loop integration with libev (see Asynchronous Programming).

Configuring yum repositories (CentOS, Red Hat)

This section assumes you know how to add an external yum repository and Linux quick start explains the steps it will perform on your distribution.
To configure the repository:

Find the appropriate repository location for your distribution in the following table.
CentOS and RHEL allow 32-bit packages to be installed on a 64-bit system.
This is usually not what you want, soensure that you use the 64-bit repository for your 64-bit system (unless you specifically want the 32-bit SDK).

Installation from source

You may install the library from source either by downloading a source archive, or by checking out the git
repository.
Follow the instructions in the archive’s README for further instructions.

Windows Installation

Windows binary packages can be found as downloads for each version listed below.
Included are the header files, release and debug variants of the DLLs and import libraries, and release and debug variants of the command line tools.
Note that the C SDK does not have any preferred installation path, and it is up to you to determine where to place libcouchbase.dll.

Be sure to select the proper package for the compiler and architecture your application is using.

If there are no binaries available for your Visual Studio version, then using a binary from any other Visual Studio version is likely to work.
Most of the issues related to mixing Visual Studio binary versions involve changing and incompatible C APIs or incompatible C Runtime (CRT) objects and functions.
Since the Couchbase C SDK does not expose a C API, and since it does not directly expose any CRT functionality, it should be safe for use so long as your application can link to the library at compile-time.
The windows runtime linker will ensure that each binary is using the appropriate version of the Visual C Runtime (MSVCRT.DLL).

2.10.1 (November 22 2018)

CCBC-997: Extract analytics queries into separate file, and expose new API as set of lcb_analytics_* functions.

CCBC-992: KV ingest mode for analytics. Ingestion mode a way to funnel analytics results back into the KV layer through mutation.

CCBC-991: Analytics Deferred Queries. Deferred queries allow to decouple the execution of an analytics query from actually fetching the results. This is very important for queries that take a long time to complete.

2.9.3 (July 18 2018)

CCBC-955:
Parse uint32 as unsigned ints instead of timeouts.
Some settings were interpreted as time values, while they should not (e.g. console_log_level, compression_min_size etc).
This issue forced the library to misinterpret user input (converter was multiplying all values to 1000000, e.g. log level was always TRACE).

CCBC-948:
Consider retry queue with only 0xb5 as empty. This allows a breakout from lcb_wait earlier (when application operates in synchronous style).
The old behaviour, where lcb_wait does not breakout until the library gets the first successful configuration, still can be restored with lcb_cntl(…​, LCB_CNTL_WAIT_FOR_CONFIG, …​).

CCBC-939:
Optimize the performance of built-in tracer.
It now uses sllist for tags container instead of Json::Value.

CCBC-958:
Check tracing span tags argument more pedantically and return error if arguments are not valid.

CCBC-956:
Combine operation id and name into single field in the threshold tracer.

CCBC-949:
Do not hardcode libevent dependencies in DEB packages.
Instead let dh_shlibdeps script to detect dependencies for each platform.
This fixes useless dependency on libevent-1 for ubuntu 18.04.

CCBC-947:
Fix build scripts for examples (when built with -DLCB_BUILD_EXAMPLES=ON).

CCBC-943
Implement option to dump TCP packets. This change introduces new cmake option, which will force library to report all incoming/outgoing TCP packets on TRACE log level.
It renders the bytes in Base64 encoding.
Also there is simple extraction tool, which beautifies packet traces, and could be used like this:

Updates in crypto API as per RFC.
This basically change of the API (ABI has preserved compatible, but v0 crypto API will return runtime error with 2.9.0 library.
From this release, all encryption key management encapsulated into crypto provider, so it does not need to expose key loader interface.
In addition, that user API is changed to conform RFC, and use noun fields instead of document (e.g.lcbcrypt_encrypt_fields).

CCBC-685:
Implementation of SCRAM-SHA{1,256,512} authentication mechanisms for
KV service. Support for SCRAM-SHA* SASL auth is disabled by
default, because it is not portable, and not every Couchbase service
supports it. But if it is necessary, it could be enabled using
lcb_cntl(…​, LCB_CNTL_FORCE_SASL_MECH, …​) operation, or
"force_sasl_mech=SCRAM-SHA512" option in connection string.

CCBC-919: More
granular settings for compression. Now it is possible to specify
minimum size of the value to be considered for compression, and also
the minimal ratio (compressed / original). See
LCB_CNTL_COMPRESSION_MIN_SIZE (or "compression_min_size=100"
in bytes), and LCB_CNTL_COMPRESSION_MIN_RATIO (or
"compression=0.9").

CCBC-916: Do not set
JSON datatype if server didn’t ack it. Fixes behavior where old
server rejecting commands as invalid when compression is enabled.

CCBC-923: Allow to
disable fast-forward map for NMV handler. See LCB_CNTL_VB_NOREMAP
("vb_noremap=true"). This option is disabled by default.

2.8.6 (April 5 2018)

CCBC-888: Add
threshold logging tracer, which tracks and reports above threshold
and orphaned operations. This is beta functionality, which is
disabled by default. To enable it, use enable_tracing=on in the
connection string.

CCBC-910: Field
encryption API. The lcbcrypto_* functions abstracts encrypted
field layout from actual crypto implementations (OpenSSL, libsodium,
etc.). The wrapper or application using libcouchbase is expected to
connect their own crypto and key providers, while libcouchbase
provides transformation of the encrypted data. See sample crypto
provider in
example/crypto.

2.8.5 (February 23 2018)

CCBC-883: Always use
built-in compression. It is not possible to unbundle the Snappy
library, as libcouchbase uses the C++ API which is not exported in
the headers. Also, compression can now work on all types of buffers,
including LCB_KV_IOV and LCB_KV_IOVCOPY. This fixes compression
in cbc-pillowfight tool.

CCBC-879: Implement
log redaction. When log_redaction=on is specified in the connection
string, the library will wrap sensitive data in the logs in special
tags, which can be processed by the cblogredaction tool from the
server distribution.

CCBC-892: Enable the
SSL trust store to be in a separate file. Trust store has to be
specified with option truststorepath=…​, otherwise the library will
expect it to be stored with the certificate in certpath=.

CCBC-888: Per
operation tracing. When compiled with tracing support (cmake
-DLCB_TRACING=ON), the library will expose the tracing API, which
allows to measure time of every data operation, and include some
extra information. The API is modeled after OpenTracing and allows
one to write custom tracers to consume this information. For more
information, see an example in
example/tracing/tracing.c.
This is uncommitted API at this time.

Also this feature includes support for new type of the server
responses, which include time spent to execute the KV command on the
server. This feature controlled by enable_tracing option in
connection string or lcb_cntl(…​, LCB_CNTL_ENABLE_TRACING,
…​).

Added basic support of JSON datatype. The library will negotiate a
mode, in which the application will see LCB_VALUE_F_JSON flag on
datatype field of the response in the operation callback, if the
cluster detected the content of the document to be valid JSON. Also
the application can send this flag on the outgoing documents to
notify the server about payload format.

when requesting timings with -T/--timings, the application will
no longer dump them periodically.Instead it will await for the
user to signal SIGQUIT and also dump them on exit. The old mode
of reporting regularly is enabled by repeating the switch more
than once (e.g. -TT).

Added the cbc-watch command to monitor server stats. By default it
tracks cmd_total_ops, cmd_total_gets and cmd_total_sets
updating stats once a second, and displaying diff with the previous
value.

CCBC-885: Do not
skip HTTP Basic authentication when password is empty.

CCBC-876: Make sure
that server authority is always specified. In some cases, when
libcouchbase generates vbucket configuration or data service is not
available, the authority of the server might be NULL. This could
cause issues, as we compare servers from configs using their
authority fields.

Note that this change does not expose anything related to
Collections API for libcouchbase. It defines hidden switches for
pillowfight tool to allow benchmark of collections. The switches are
not documented and might be removed in the future. Use with care.

Generate only beer:<seqno> keys:

cbc pillowfight --separator : --collection beer

Using many --collection will alternate in generating
beer:<seqno>, brewery:<seqno> keys (default separator is
":"):

CCBC-874: Dynamic
authenticator. Note that this feature should not be considered at
public interface. To use it, application have to define two
callbacks, which will return username and password dependending on
bucket name and hostname/port of the endpoint.

2.8.3 (November 22 2017)

Additions and bug fixes in this version:

CCBC-415: Fixes in
IPv6 support. To use IPv6 addresses, the application should connect
to IPv6-enabled Couchbase Server, and explicitly switch on option
via connection string ipv6=allow or ipv6=only, where first variant
permits the library to use both IPv6 and IPv4, and the second — disables IPv4. Alternatively this setting controlled with
LCB_CNTL_IP6POLICY and lcb_cntl.

2.8.0 (August 31 2017)

Known Isssues:

As reported in Issue
CCBC-838, version 2.8.0
should have Error Maps enabled by default, but it does not. Users may
work around this issue by specifying errmap_enable=true in
connection string or setting it programmatically:

Mask LOCKED status code for backward compatibility. This code (as
well as others possible codes with 'item-locked' attribute) replaced
with LCB_KEY_EEXISTS for SET, REPLACE and DELETE operations, and
with LCB_ETMPFAIL for the rest.

2.7.7 (August 17 2017)

Implement new function lcb_ping3, which sends NOOP-like message to
each service in the cluster and allows to measure latency along with
health status of the connection. Might be useful for
application-side keep-alive mechanisms.

2.7.6 (July 11 2017)

Expose enhanced errors for data commands. Couchbase Server 5 might
return additional information about errors in the response body.
According to SDK-RFC-28, the library allow user code to inspect this
information using following functions:

lcb_resp_get_error_context(int, const lcb_RESPBASE *)

lcb_resp_get_error_ref(int, const lcb_RESPBASE *)

They both return non-NULL strings if any of error information
accessible. The lifetime of these fields limited by lifetime of the
response object. * Issues:
CCBC-781

Report contextualized error messages during negotiation. The event
reference could be used to find more details about authentication
errors in the server logs.

Add cluster admin provider. This provider doesn’t do anything except
serve as a source of management hostnames. And the library will fall
back to it when bucket is not specified for cluster management
connections.

Enable background polling for configuration changes. This allows the
client to periodically poll for configuration changes. This feature
is disabled by default. You can use
the config_poll_interval setting to enable it in the connection
string.

Enable TCP Keepalive for newly created sockets. Newly created
sockets have TCP keepalive enabled in order to avoid firewalls
breaking connections due to inactivity. TCP Keepalive does not yet
work for the libuv plugin (e.g. nodejs). You can use
the tcp_keepalive=false directive in the connection string to
disable it.

2.7.4 (April 21 2017)

Send SELECT_BUCKET command by default if server supports it. This
enables new-style 'RBAC' authentication by default. In 2.7.3 users
were required to use select_bucket=true in the connection string to
enable this feature. In this version, the option is still available
but is now mainly useful to disable it.

Improve lcb_AUTHENTICATOR API. This provides better documentation
and some API/design/implementation fixes to the authenticator
interface. The authenticator may be useful for integrators/wrappers
who wish to correlate multiple credentials with their buckets. Note
that the use of lcb_AUTHENTICATOR is not required for RBAC
support. In order to use RBAC, simply make use of the username field
in the lcb_create_st struct, or the usernameparameter in the
connection string.

Fix bug where client would not recover from failover. Clients from
version 2.7.1 through 2.7.3 would not obtain a new cluster map after
a node had been failed over (e.g. by hitting the "fail over" button
in the UI).

2.7.3 (March 21 2017)

Known Isssues:

As reported in Issue
CCBC-766, versions
2.7.1, 2.7.2, and 2.7.3 may result in a stuck client, where operations
may consistently fail after a node has been failed over, even if a
replica node is available. Users may work around this issue by:

Rebalancing the cluster

Bringing the failed over node online

Downgrading to 2.7.0 or lower.

Additions and bug fixes in this version:

Provide the ability to send the SELECT_BUCKET when establishing a
to a server. This is a building block allowing us to use
'RBAC'/username auth in the future. Note that this requires
the select_bucket=true option in the connection string or
equivalent, and that this feature as a whole is considered
experimental.

Provide an option to disable DNS-SRV lookups. Because DNS SRV
lookups often result in no result (i.e. NXDOMAIN) - which takes
longer, allowing to disable such lookups may speed up startup time.
This option is available via the connection string, using dnssrv=off

Send client/user-specific identifier in User-Agent HTTP header. The
library already does this for data nodes (Memcached). Using it in
HTTP services allows better supportability when diagnosing issues by
reading the HTTP logs.

Provide experimental Analytics support. This allows access to the
Couchbase Analytics Service, available in some pre-release builds.
API and syntax wise, Analytics is very similar to N1QL. To use the
analytics service, set the LCB_CMDN1QL_F_CBASQUERY bit
in lcb_CMDN1QL::cmdflags, and provide the
appropriate host:port combination in
the lcb_CMDN1QL::host field. - Currently, analytics support is not
used in the cluster map/configuration.

2.7.2 (February 21 2017)

Known Isssues:

As reported in
Issue CCBC-766, versions
2.7.1, 2.7.2, and 2.7.3 may result in a stuck client, where operations
may consistently fail after a node has been failed over, even if a
replica node is available. Users may work around this issue by:

Rebalancing the cluster

Bringing the failed over node online

Downgrading to 2.7.0 or lower.

This release consists of additional internal refactoring and some
improved logging messages. There is enhanced experimental XATTR support.
This release also contains some bug fixes:

Fix build issues on FreeBSD. This allows normal BSD make to be used,
rather than forcing gmake

Fixed broken JIRA link in README

Fix hanging SSL connections in IOCP/Completion mode. This would
sometimes stall the connection by not requesting a write if a read
was in progress. This would result in the command not being sent and
the client hanging. Note that this only affects completion-style I/O
plugins such as IOCP and libuv.

2.7.1 (January 20 2017)

Known Isssues:

As reported in
Issue CCBC-766, versions
2.7.1, 2.7.2, and 2.7.3 may result in a stuck client, where operations
may consistently fail after a node has been failed over, even if a
replica node is available. Users may work around this issue by:

Rebalancing the cluster

Bringing the failed over node online

Downgrading to 2.7.0 or lower.

This release consists of additional internal refactoring. More internals
have been converted to C++.

Provide XATTR (Extended Attribute) prototype support. This provides
a prototype implementation of xattrs, allowing the client to access
extended (hidden) attributes of a document. This feature can be used
on the client side by simply setting
the LCB_SDSPEC_F_XATTRPATH bit in the lcb_SDSPEC::options field.

Add automatic DNS SRV record lookup when simple hostname supplied.
The library will now automatically attempt to look up SRV records
for various couchbase services if only one host is present in the
connection string. Automatic lookup will not be performed if more
than a single host is provded. See the Java
Documentationon
the matter (go to the bottom of the page).

2.6.3 (September 27 2016)

Fix memory corruption for some JSON APIs when no rows are returned.
This fixes a bug where the JSON parser would read from garbage
memory when parsing a response that had no rows, but due to a slow
network, would be received in multiple chunks. This affects N1QL,
CBFT, and View APIs.

Allow to adjust bytes to read per event loop iteration. This allows
applications with high network throughput but low CPU capacity to
prevent the library from oversaturating a specific event callback
invocation or starve other sockets. It may be controlled through
the read_chunk_size connection string option or
via lcb_cntl_string.

Use htonll for CAS values. This allows a consistent representation
of CAS values regardless of underlying platform. This allows
interoperability between other SDKs with respect to exchanging CAS
values. This however may break interoperability with older versions
of the same SDK, if the CAS value is being passed around (which it
shouldn’t be).

New subdocument additions. This adds
the LCB_SUBDOC_F_MKDOCUMENT flag which allows document creation
if the document does not exist, and can be used for mutation
operations which may create new paths or values.
TheLCB_SUBDOC_CMD_GET_COUNT is also added, which is a new
command which retrieves the number of elements (for an array) or
key-value items (within an object/dictionary) of a given path. Both
these features require Couchbase Server 4.6 (or its prereleases).

C SDK Version 2.6.2 (July 27 2016)

Don’t crash on high number of FDs with select plugin.
Because select(2) can only accomodate up to a certain number of file
descriptors in the application, if opening a socket results in a
too-high-numbered FD, the plugin will return an error rather than
silently failing during polling.

Fix crash on shutdown with completion-based I/O. The crash was a
result of dereferencing the lcb_t after it had been destroyed. This
bug affected completion-based I/O subsystems such as libuv and IOCP.

Do not require operation field to be set on lcb_CMDSTORE. Starting
from this version, a new lcb_storage_t constant,LCB_UPSERT has
been added with a value of 0. This means that upsert operations no
longer need to explicitly useLCB_SET, it being the default.

C SDK Version 2.6.1 (June 21 2016)

Index management API now properly handles 'fields' field. Previously
this was treated as a csv string, when it is in fact a JSON array.

pillowfight now has a --populate-only option, which is useful when
simply trying to populate buckets with large amounts of data.

Allow to bypass OpenSSL initialization. This allows applications
which already have OpenSSL intialization code in place to suppress
libcouchbase’s own OpenSSL initialization code. You can disable SSL
initialization by usingssl=no_global_init in the connection
string.

Allow to toggle sending of multiple credentials in N1QL queries. You
can use the LCB_CMD_F_MULTIAUTH in
the lcb_CMDN1QL::cmdflags field to indicate that multiple
credentials should be added. Otherwise only the current bucket’s
credentials will be sent.

Fix infinite loop on completion (UV,nodejs,IOCP) type IO plugins.
This bug would be triggered when only a single server remained in
the cluster and that single server failed. This would result in the
client never being able to perform operations due to a delayed
reference count decrement.