Couchbase Lite — In C!

Couchbase Lite has been available since 2014, targeting the iOS, Android and .NET platforms, and secondarily macOS and Windows. To that end, we’ve exposed APIs in the preferred languages of those platforms: Java, Objective-C, Swift, and C#.

But surely there are other uses for an embedded NoSQL database with best-in-class sync capabilities! It’s ideally suited to the emerging Internet Of Things; developers have come to us wanting to run Couchbase Lite on embedded Linux boards such as the Raspberry Pi. Others have asked for bindings to more languages such as Python or Go.

I’m happy to say that we’re taking steps toward these use cases, by introducing Couchbase Lite For C. This is a full implementation of Couchbase Lite with:

• An ANSI C API whose functions are mostly one-to-one compatible with the class methods in the Couchbase Lite 2.x API. Some details are necessarily different because C does not come with automatic memory management or collection data structures, but if you’re used to the existing APIs you should be right at home — see some small code examples. There is also a C++ API, implemented as a wrapper around the C API.
• No dependence on a high-level runtime like .NET or JVM, or a large proprietary class library like Cocoa.
• Minimal OS dependencies. It should run on any Unix-like OS (or recent MS Windows); it just needs a filesystem, a C++ standard library, and TCP/IP networking for the replicator.
• Modest hardware needs: think Raspberry Pi (but not Arduino). That means tens of megabytes of available RAM, hundreds of MHz of CPU, and enough persistent storage for your database.
• Full source code under an Apache 2 license, like the other flavors of Couchbase Lite. (Enterprise Edition features, available under a commercial license, add a small amount of closed source.)

What’s the catch? It’s not finished yet — this is early access to an alpha-quality project. For details, see the “Future Plans” section, below.

…And For Other Languages

Couchbase Lite For C will help bring Couchbase Lite to other languages and platforms. C is a lingua franca, so every language has tools for binding to C APIs. This makes it easy to write the necessary glue to call Couchbase Lite, and then craft an idiomatic API atop that. As a proof of concept, we’re including a Python 3 binding in the same Github repository.

The C API has been crafted to be easy to bind. It’s as object-oriented as possible, with regular function names that concatenate the “class” and “method” name. “Objects” are reference-counted, to make them easy to manage from a garbage-collected runtime. A Document’s properties can be optionally accessed as a JSON string if it’s simpler to use your language’s JSON parser. We’ve even given client code the ability to schedule when and where notification callbacks are invoked, so you can adapt to whatever concurrency model your language (or OS) supports.

Architecture

The C API for Couchbase Lite is a straightforward extension of our 2.x architecture. For the 2.0 release in 2018 we reimplemented Couchbase Lite with a platform-agnostic core component written in C++. This core provides a (non-public) C API which the various implementations of Couchbase Lite bind to, exposing their own public APIs in Java, C#, Swift or Objective-C.

For this new project we wrote an adapter (again in C++) that mostly just reshapes that internal C API to make it clearer, easier to use, and conformant to our cross-platform API spec. This adapter is statically linked with the core library to produce a single binary.

Architecture diagram showing layering of Couchbase Lite For C

This adapter is pretty simple: so far it’s under 2,000 lines of C/C++ including the headers. The vast majority of the functionality comes from Couchbase Lite Core, which has already been battle-tested for a year on two Unix-based platforms (Android and Darwin) and Windows. So development of the C API itself is pretty straightforward, letting us put more work into porting.

Future Plans

Couchbase Lite For C is under active development, but it’s not finished yet. We’re giving you early access to an alpha-quality project. The APIs are pretty solid, but some functionality isn’t hooked up; there’s been little testing; and we haven’t yet ported it beyond macOS, Windows, and Ubuntu. It’s not yet an official product, and we won’t provide commercial support for it until it’s complete and high-quality.

We’re making it available now because we know there’s demand (a few intrepid developers have already resorted to exploring our internal C APIs!) and because we could use help finishing it:

• The embedded platform landscape is remarkably fragmented compared to mobile, desktop or server. We don’t have every IoT development board, or every embedded Linux distro. Multi-platform support for low-level code can be tricky, especially with multiple compilers (Clang, GCC, MSVC) in the mix. There are also some exotic non-UNIX operating systems in the embedded space, like VxWorks, QNX, RIOT…
• Resource-constrained environments can be challenging to test for. Out-of-memory errors are a thing! Power consumption often matters a lot. And just hooking up a source-level debugger can be tricky. But as Eric Raymond said, “given enough eyeballs, all bugs are shallow.”

How You Can Contribute

Development work is ongoing and in the open, with commits going directly to the Github repository. We encourage your bug reports, suggestions, and pull requests. (If you feel like contributing, please read our guidelines first.) We hope you’ll join with us in bringing Couchbase Lite to more platforms and languages than ever before.