keradb C/C++ SDK

Native C and C++ bindings for the keradb embedded document database.

Requirements

• C compiler (GCC, Clang, MSVC)
• C++11 or higher (for C++ wrapper)
• CMake 3.10+ (optional, for building)
• keradb native library

Installation

Using CMake

cd sdks/cpp
mkdir build && cd build
cmake ..
make
sudo make install

Manual Compilation

C Example:

gcc -o myapp main.c -L../../../target/release -lkeradb -I../../../include

C++ Example:

g++ -std=c++11 -o myapp main.cpp -L../../../target/release -lkeradb -I../../include

Quick Start

C API

#include "keradb.h"
#include <stdio.h>
#include <stdlib.h>

int main() {
    // Create database
    keradbDB db = keradb_create("mydb.ndb");
    if (!db) {
        fprintf(stderr, "Failed to create database\n");
        return 1;
    }
    
    // Insert document
    const char* json = "{\"name\":\"Alice\",\"age\":30}";
    char* id = keradb_insert(db, "users", json);
    if (id) {
        printf("Inserted ID: %s\n", id);
        keradb_free_string(id);
    }
    
    // Find by ID
    char* doc = keradb_find_by_id(db, "users", id);
    if (doc) {
        printf("Found: %s\n", doc);
        keradb_free_string(doc);
    }
    
    // Close
    keradb_close(db);
    return 0;
}

C++ API

#include "keradb.hpp"
#include <iostream>

int main() {
    try {
        // Create database
        auto db = keradb::Database::create("mydb.ndb");
        
        // Insert document
        auto id = db.insert("users", R"({
            "name": "Alice",
            "age": 30,
            "email": "alice@example.com"
        })");
        std::cout << "Inserted ID: " << id << std::endl;
        
        // Find by ID
        auto doc = db.findById("users", id);
        std::cout << "Found: " << doc << std::endl;
        
        // Update
        auto updated = db.update("users", id, R"({
            "name": "Alice Smith",
            "age": 31
        })");
        
        // Find all
        auto users = db.findAll("users");
        std::cout << "All users: " << users << std::endl;
        
        // Delete
        db.remove("users", id);
        
    } catch (const keradb::Exception& e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }
    
    return 0;
}

API Reference

C API

See keradb.h for the complete C API.

Key Functions:

• keradbDB keradb_create(const char* path) - Create database
• keradbDB keradb_open(const char* path) - Open database
• void keradb_close(keradbDB db) - Close database
• char* keradb_insert(keradbDB db, const char* collection, const char* json_data) - Insert
• char* keradb_find_by_id(keradbDB db, const char* collection, const char* doc_id) - Find
• char* keradb_update(keradbDB db, const char* collection, const char* doc_id, const char* json_data) - Update
• int keradb_delete(keradbDB db, const char* collection, const char* doc_id) - Delete
• char* keradb_find_all(keradbDB db, const char* collection, int limit, int skip) - Find all
• int keradb_count(keradbDB db, const char* collection) - Count
• char* keradb_list_collections(keradbDB db) - List collections
• void keradb_free_string(char* s) - Free returned strings

C++ API

The C++ wrapper provides RAII and exception-safe interface:

Database Class:

• static Database create(const std::string& path) - Create database
• static Database open(const std::string& path) - Open database
• std::string insert(const std::string& collection, const std::string& json) - Insert
• std::string findById(const std::string& collection, const std::string& id) - Find
• std::string update(const std::string& collection, const std::string& id, const std::string& json) - Update
• void remove(const std::string& collection, const std::string& id) - Delete
• std::string findAll(const std::string& collection, int limit = -1, int skip = 0) - Find all
• int count(const std::string& collection) - Count
• std::string listCollections() - List collections
• void sync() - Sync to disk

Building Examples

cd sdks/cpp
mkdir build && cd build
cmake ..
make
./basic_example

Examples

See the examples directory for more usage examples.

Benchmarks

The SDK includes a comprehensive benchmark comparing KeraDB vs SQLite performance.

Running the Benchmark

Windows (PowerShell):

.\build-benchmark.ps1 -Run

Manual build with CMake:

mkdir build && cd build
cmake -DBUILD_BENCHMARKS=ON ..
make
./benchmark

Benchmark Results

Tested on Windows 11, Intel Core i7, Release build

Small Dataset (100 records)

Operation	KeraDB (ms)	SQLite (ms)	Speedup
INSERT	3.05	44.06	14.5x faster
READ BY ID	0.27	1.00	3.7x faster
READ ALL	0.27	0.06	0.22x
COUNT (100x)	0.02	0.94	46x faster
UPDATE	1.52	33.36	22x faster
DELETE	0.75	45.62	61x faster

Medium Dataset (1,000 records)

Operation	KeraDB (ms)	SQLite (ms)	Speedup
INSERT	28.05	44.00	1.57x faster
READ BY ID	5.44	8.77	1.61x faster
READ ALL	7.57	0.22	0.03x
COUNT (100x)	0.01	0.97	124x faster
UPDATE	7.23	41.83	5.8x faster
DELETE	8.13	36.87	4.5x faster

Large Dataset (10,000 records)

Operation	KeraDB (ms)	SQLite (ms)	Speedup
INSERT	238.39	51.41	0.22x
READ BY ID	6.99	11.30	1.62x faster
READ ALL	89.24	1.77	0.02x
COUNT (100x)	0.01	1.02	137x faster
UPDATE	7.39	37.69	5.1x faster
DELETE	7.89	36.99	4.7x faster

Performance Summary

KeraDB excels at:

• ✅ COUNT operations - 46-137x faster (in-memory metadata)
• ✅ Single document lookups - 1.6-3.7x faster
• ✅ Updates - 5-22x faster
• ✅ Deletes - 4.5-61x faster
• ✅ Small/medium inserts - up to 14x faster

SQLite excels at:

• ✅ Bulk inserts at large scale (10k+ with prepared statements)
• ✅ Table scans (READ ALL) - optimized columnar access

Conclusion: KeraDB is ideal for document-oriented workloads with frequent single-record CRUD operations, while SQLite is better suited for bulk data operations and relational queries.

License

MIT License - See LICENSE file for details