Awesome
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.
Goals
- 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
- Can be bound to other languages like Python, Go, or 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
- Peer-to-peer replication
- Schemaless JSON data model
- Minimal platform dependencies: C++ standard library, filesystem, TCP/IP, libz (macOS / Linux), libicu (Linux)
- Broad official OS support
- macOS (x86_64 and arm64)
- Debian 9/10 (including Raspbian / Raspberry Pi OS) and Ubuntu 20.04 (x86_64, armhf, arm64)
- Windows (x86_64 only)
- iOS (device and simulator archs)
- Android (armeabi-v7a, arm64-v8a, x86, x86_64)
- 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
Examples
C
// Open a database:
CBLError error;
CBLDatabaseConfiguration config = {FLSTR("/tmp")};
CBLDatabase* db = CBLDatabase_Open(FLSTR("my_db"), &config, &error);
// Create a document:
CBLDocument* doc = CBLDocument_CreateWithID(FLSTR("foo"));
FLMutableDict props = CBLDocument_MutableProperties(doc);
FLSlot_SetString(FLMutableDict_Set(props, FLStr("greeting")), FLStr("Howdy!"));
// Save the document:
CBLDatabase_SaveDocument(db, doc, &error);
CBLDocument_Release(doc);
// Read it back:
const CBLDocument *readDoc = CBLDatabase_GetDocument(db, FLSTR("foo"), &error);
FLDict readProps = CBLDocument_Properties(readDoc);
FLSlice greeting = FLValue_AsString( FLDict_Get(readProps, FLStr("greeting")) );
CBLDocument_Release(readDoc);
C++
NOTE: The C++ API is a volatile API which means that the API is not finalized, and may change in future releases.
// Open a database:
cbl::Database db(kDatabaseName, {"/tmp"});
// Create a document:
cbl::MutableDocument doc("foo");
doc["greeting"] = "Howdy!";
db.saveDocument(doc);
// Read it back:
cbl::Document readDoc = db.getMutableDocument("foo");
fleece::Dict readProps = readDoc.properties();
fleece::slice greeting = readProps["greeting"].asString();
Documentation
- Couchbase Lite documentation is a must-read to learn the architecture and the API concepts, even though the API details are different here.
- API documentation in the header files
- Using Fleece — Fleece is the API for document properties
- Contributor guidelines, should you wish to submit bug fixes, tests, or other improvements
Building It
Source Code
This project contains submodules in multiple levels. Please make sure all submodules are checked out before building the project.
git clone https://github.com/couchbase/couchbase-lite-C.git
cd couchbase-lite-C
git submodule update --init --recursive
Unix (Linux / macOS)
Dependencies:
- GCC 7+ or Clang
- CMake 3.10+
- (Linux) ICU development libraries (
apt-get install icu-dev
) - (Linux) ZLIB development libraries (
apt-get install zlib1g-dev
)
Steps:
-
Prepare and build project with CMake.
# At the project directory, create a build directory: mkdir build && cd build # Prepare project. Specify CMAKE_INSTALL_PREFIX for the installation directory when running `make install`. # Add -DSTRIP_SYMBOLS=ON to generate a separate debug symbol file and strip private symbols from the built shared library. cmake -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_INSTALL_PREFIX=`pwd`/output .. # Build: make
-
Install the built library and headers to the location specified by
CMAKE_INSTALL_PREFIX
make install
The installation will contain header files in the
include
folder and a shared library file in thelib
folder.
Linux (Cross Compile)
NOTE: Due to the complexity of cross compiling, these instructions are very high level on purpose. If you are curious about more fine-grained details you can check out the cross compilation script we use.
Dependencies:
- Cross compiler based on GCC 7+ or clang
- CMake 3.10+
- (in sysroot) ICU development libraries
- (in sysroot) ZLIB development libraries
Steps:
The steps are similar to the steps for building the regular linux library above. The difference is that you will also need
to prepare the CMake toolchain file that sets up the cross compiler and sysroot
for the cross compilation.
When running the cmake
to prepare the build project, add CMAKE_TOOLCHAIN_FILE
option to specify the CMake toolchain file:
cmake -DCMAKE_TOOLCHAIN_FILE=<YOUR/toolchain.cmake> -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_INSTALL_PREFIX=`pwd`/output ..
Windows
Dependencies:
- Visual Studio Toolset v141+ (Visual Studio 2017+)
- CMake 3.10+
Steps:
-
Prepare project with CMake.
# Using powershell, at the project directory, create a build directory: md build cd build # Prepare project. Specify CMAKE_INSTALL_PREFIX for the installation directory: cmake -G "Visual Studio 15 2017" -A x64 -DCMAKE_INSTALL_PREFIX="$pwd/output" ..
-
Build and Install
cmake --build . --config MinSizeRel --target install
The installation will contain header files in the
include
folder, a dll file in thebin
folder and a lib file in thelib
folder.
Xcode on macOS
:warning: Do not use Xcode 13 because of a downstream issue :warning:
- Open the Xcode project
CBL_C.xcodeproj
- Select scheme
CBL_C Framework
- Build
The result is CouchbaseLite.framework
in your Xcode Build Products/Debug
directory (the path depends on your Xcode settings.)
Testing It
CMake on Unix
- Follow the steps in building
- Build the test project
make CBL_C_Tests
- Run the tests in
test
directory./CBL_C_Tests -r list
(for cross compile, this step needs to be done on the target system)
CMake on Windows
- Follow the steps in building
- Build the test project
cmake --build . --target CBL_C_Tests
- Run the tests in
test\Debug
directory.\CBL_C_Tests.exe -r list
With Xcode on macOS
- Open the Xcode project from the Building section
- Select scheme
CBL_Tests
- Run
Using It
Generic instructions
- In your build settings, add the paths
include
andvendor/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.
Other Language Bindings
All of these (even C++) have no official support by Couchbase.
If you've created a language binding, please let us know by filing an issue, or a PR that updates the list below.
- C++: Already included; see
include/cbl++
- Go (Golang): Third-party, in progress
- Python: couchbase-lite-python
- Rust: couchbase-lite-rust