Skip to content
C language bindings for the Couchbase Lite embedded NoSQL database engine
Branch: master
Clone or download
SJLC and snej python binding: workaround for python 3.5 distutils bug
The cffi compile method uses python distutils under the hood,
so it is subject to bugs in distutils. Turns out there is a
bug in python 3.5 distutils for unix platforms: absolute paths
for library dirs do not work, causing link failures.

Avoid this bug, when present, by ensuring path to couchbase build dir
is always relative.
Latest commit 428e488 Jun 5, 2019

Couchbase Lite For C

This is a cross-platform version of the Couchbase Lite embedded NoSQL syncable database, with a plain C API. The API can be used directly, or as the substrate for binding to other languages like Python, JavaScript or Rust.

As of July 2019, this project is approaching beta status. The API is nearly complete and most of the functionality is implemented, but there are missing pieces and only limited testing.


  • C API
    • Similar to to other Couchbase Lite platforms (Java, C#, Swift, Objective-C)
    • Clean and regular design
    • Comes with a C++ wrapper API, implemented as inline calls to C
    • Experimental Python binding (made using cffi)
    • Can be bound to other languages like JavaScript
  • Same feature set as other Couchbase Lite platforms
    • Schemaless JSON data model
      • Standard CRUD operations
      • Efficient binary blob support
      • Timed document expiration
      • Database encryption (Enterprise Edition only)
    • Powerful query language based on Couchbase's N1QL
      • Index arbitrary JSON properties or derived expression values
      • Full-text search (FTS)
    • Multi-master bidirectional replication (sync) with Couchbase Server
      • Fast WebSocket-based protocol
      • Transfers document deltas for minimal bandwidth
      • Replicator event listeners
      • Replicator online/offline support and retry behavior
      • Replicator TLS/SSL support (in progress)
      • Peer-to-peer replication
  • Minimal platform dependencies: C++ standard library, filesystem, TCP/IP
  • Broad OS support
    • macOS, for ease of development
    • Common Linux distros, esp. Ubuntu, Fedora, Raspbian (q.v.)
    • Windows
    • iOS
    • Android (but we have a Couchbase Lite For Android already, with a Java API)
  • Runs on Raspberry-Pi-level embedded platforms with…
    • 32-bit or 64-bit CPU
    • ARM or x86
    • Hundreds of MB RAM, hundreds of MHz CPU, tens of MB storage
    • Linux-based OS
    • Stretch goal: Simpler embedded kernels like mbedOS or ESP-IDF.



// Open a database:
CBLError error;
CBLDatabaseConfiguration config = {"/tmp", kCBLDatabase_Create};
CBLDatabase* db = CBLDatabase_Open("my_db", &config, &error);

// Create a document:
CBLDocument* doc = CBLDocument_New("foo");
FLMutableDict props = CBLDocument_MutableProperties(doc);
FLSlot_SetString(FLMutableDict_Set(dict, FLStr("greeting")), FLStr("Howdy!"));

// Save the document:
const CBLDocument *saved = CBLDatabase_SaveDocument(db, doc, 

// Read it back:
const CBLDocument *readDoc = CBLDatabase_GetDocument(db, "foo");
FLDict readProps = CBLDocument_Properties(readDoc);
FLSlice greeting = FLValue_AsString( FLDict_Get(readProps, FLStr("greeting")) );


// Open a database:
cbl::Database db(kDatabaseName, {"/tmp", kCBLDatabase_Create});

// Create a document:
cbl::MutableDocument doc("foo");
doc["greeting"] = "Howdy!";

// Read it back:
cbl::Document doc = db.getMutableDocument("foo");
fleece::Dict readProps = doc->properties();
fleece::slice greeting = readProps["greeting"].asString();


# Open a database:
db = Database("db", DatabaseConfiguration("/tmp"));

# Create a document:
doc = MutableDocument("foo")
doc["greeting"] = "Howdy!"

# Read it back:
readDoc = db.getDocument("foo")
readProps =
greeting = readProps["greeting"]


Building It

With CMake on Unix (now including Raspberry Pi!)


  • GCC 7+ or Clang
  • CMake 3.9+
  • ICU libraries (apt-get install icu-dev)
  1. Clone the repo
  2. Check out submodules (recursively)
  3. mkdir build_cmake
  4. cd build_cmake
  5. cmake .. && make -j5
  6. ./test/CBL_C_Tests -r list

The library is at build_cmake/ (Or .DLL or .dylib)

With CMake on Windows

(Much like building on Unix. Details TBD)

With Xcode on macOS

  1. Clone the repo
  2. Check out submodules (recursively)
  3. Open the Xcode project in the Xcode subfolder
  4. Select scheme CBL_C Framework
  5. Build

The result is CouchbaseLite.framework in your Xcode Build Products/Debug directory (the path depends on your Xcode settings.)

To run the unit tests:

  1. Select scheme CBL_Tests
  2. Run

Python Bindings (experimental)

This only works on Mac so far. And it assumes that Xcode puts build output in a build subdirectory next to the project file. (Want to fix this? Edit and look at the "# FIX" lines.)


  • Python 3 (only tested with 3.7)
  • pip (which might be named pip3 on your system)
  • The Python cffi package ... to install it, run pip install cffi
  1. Build the native library. (If using Xcode, build the "CBL_C Dylib" target.)
  2. cd python
  3. ./
  4. python3 -- some tests. Should run without throwing exceptions.

If the tests immediately crash after logging a message like "ERROR: Interceptors are not working", this means that your Couchbase Lite library was built with the Address sanitizer enabled, probably because you built the 'CBL_Tests' scheme. Instead, select the 'CBL_C Dylib' scheme and build that; then go back to step 3.

Using It

Generic instructions

  • In your build settings, add the paths include and vendor/couchbase-lite-core/vendor/fleece/API (relative to this repo) to your header search paths.
  • In your linker settings, add the dynamic library.
  • In source files, add #include "cbl/CouchbaseLite.h".

With Xcode on macOS

  • Add CouchbaseLite.framework (see instructions above) to your project.
  • In source files, add #include "CouchbaseLite/CouchbaseLite.h".
  • You may need to add a build step to your target, to copy the framework into your app bundle.
You can’t perform that action at this time.