KoutenDB Driver Installation Guide

This document separates published driver packages from repository-local driver foundations. The English README records released package versions; this file is the canonical setup and native-library reference.

KoutenDB drivers currently use two paths:

  • Native TCP wire drivers for cluster-oriented use.
  • C ABI wrappers for embedded/local use and language binding stability.

The CLI provides a small driver discovery surface:

kouten driver list
kouten driver info rust
kouten driver install rust
kouten driver install rust --manifest-path=/path/to/Cargo.toml

driver install prints the official package/repository path and setup command. For Rust, target selection is shell-friendly: use --manifest-path=FILE, --project-dir=DIR, KOUTEN_DRIVER_MANIFEST, or KOUTEN_DRIVER_PROJECT. It does not execute package-manager commands unless --execute is passed.

The Nim package is available through Nimble. Rust, JavaScript / TypeScript, PHP, Python, Go, and the C++ source release are published independently from the core. Installing one of those packages installs a driver, not a KoutenDB server. Repository-local Swift, C#, and Kotlin foundations are not published packages; their examples assume a local clone of this repository.

Native TCP connects to a running server without libkoutendb. Embedded mode needs the native shared library and cannot be substituted by a TCP package. The old drivers/go directory is retained as a compatibility fixture; use the external Go module below for new applications. API coverage differs by driver and transport; consult the driver’s compatibility table before migrating.

Build the Native Library

Most C ABI wrappers need lib/libkoutendb.so:

scripts/build_capi.sh

This is the canonical C ABI build. It compiles lib/libkoutendb.so with -d:ssl, so kouten_connect_auth_tls is available to Rust, Node native addons, PHP FFI, C++, C#, Swift, Kotlin, Go, and other wrappers without each driver duplicating Nim flags.

For native wire driver tests, build koutend:

nim c -d:release -d:ssl --nimcache:/tmp/nimcache_koutend -o:src/koutend src/koutend.nim

Nim

Install from Nimble:

nimble install koutendb
kouten --help

Then import the public API:

import koutendb

var db = koutendb.open(dataDir = "data")
let id = db.put("hello", ring = "docs")
echo db.get(id)

From a source checkout, run:

scripts/test_core.sh

C ABI

See the C ABI Reference for the complete application-facing surface, ownership rules, and opaque handle lifecycles.

Include include/koutendb.h and link lib/libkoutendb.so:

scripts/build_capi.sh
gcc examples/cabi_contract.c -Iinclude -Llib -lkoutendb -Wl,-rpath,'$ORIGIN/../lib' -o bin/cabi_contract
LD_LIBRARY_PATH=lib bin/cabi_contract

Thread-safety contract:

  • kouten_init() is idempotent.
  • kouten_last_error() returns text owned by KoutenDB. Copy it before the next KoutenDB C ABI call on the same thread.
  • Do not call kouten_close() concurrently with any other operation on the same handle.
  • If a driver shares one handle across threads, serialize calls around that handle. Separate handles may be used independently.

kouten_open_dir retains its existing buffered WAL behavior. Drivers that need strong durability or the ring-local disk read layout should use the additive kouten_open_dir_options call. The segment diagnostics and bounded maintenance calls return length-delimited JSON allocated by KoutenDB; release those buffers with kouten_free just like kouten_get results.

The same additive ABI v2 surface includes immutable generation checkpoints:

  • kouten_checkpoint_create_json
  • kouten_checkpoint_status_json
  • kouten_checkpoint_list_json
  • kouten_checkpoint_cleanup_json
  • kouten_checkpoint_restore_json

These functions return the same koutendb.checkpoint-*.v1 JSON shapes as the Nim API and CLI. Creation requires a persistent embedded handle. The remaining functions operate on filesystem paths and still require kouten_init() before use. Returned buffers must be released with kouten_free.

Application bindings can also expose the remaining high-level Nim workflows without reproducing core logic: named retrieval/search profiles, retrieval plans, ring summaries, versioned RAG envelopes, ring-profile writes, JSONL dump/import, locality reports, explicit packing/compaction, operational verification, and plain or encrypted backup/restore. Most structured results use length-delimited JSON so bindings can retain their native public types while sharing one core contract.

The current ABI version remains 2. These functions are additive and do not change existing struct layouts or symbols, so drivers that require ABI v2 keep working while newer wrappers may bind the additional symbols explicitly.

Python

The Python driver is released as a separate native TCP wire driver:

python3 -m pip install koutendb
KOUTENDB_CORE_DIR=/path/to/koutendb python3 -m unittest discover -s tests

Example:

from koutendb import KoutenClient

db = KoutenClient.connect("127.0.0.1:17301")
doc_id = db.put("docs", b'{"title":"hello"}')
print(db.get(doc_id))
db.close()

JavaScript / TypeScript

The published JavaScript / TypeScript driver is a Node-API wrapper over the KoutenDB C ABI:

Install it in an application:

npm install koutendb

Build the KoutenDB core shared library first and set KOUTENDB_CORE_DIR during install/rebuild. See the driver repository README for the full setup flow.

GitHub v0.2.0 also provides TcpClient through koutendb/tcp, without a native addon or libkoutendb. That version is not yet published to npm: the npm install command above still installs v0.1.5. To use the GitHub release, follow its native TCP setup guide.

The core repository also keeps a repository-local native TCP wire driver used for protocol smoke tests:

nim c -d:release --nimcache:/tmp/nimcache_koutend -o:src/koutend src/koutend.nim
node --test drivers/node/test/*.test.js
bun test drivers/node/test-bun/*.test.ts

Repository-local wire-driver example:

import { KoutenClient } from "./drivers/node/src/index.js";

const db = KoutenClient.connect("127.0.0.1:17301");
const id = await db.put("docs", Buffer.from('{"title":"hello"}'));
console.log((await db.get(id)).toString("utf8"));
await db.close();

Rust

The Rust driver provides a default C ABI wrapper and optional native TCP:

For native TCP without libkoutendb:

cargo add koutendb --no-default-features --features tcp

For the existing C ABI API, install it with default features:

cargo add koutendb

Or ask the KoutenDB CLI to print the official setup command:

kouten driver install rust --manifest-path=/path/to/Cargo.toml

For C ABI mode, build the KoutenDB core shared library first and set KOUTENDB_CORE_DIR or KOUTENDB_LIB_DIR when building/testing the Rust project. See the Rust driver repository README for the full setup flow.

Go

The Go driver is published as a separate module, requiring Go 1.26 or newer:

go get github.com/puffball1567/koutendb-go@v0.1.0

Native TCP example inside an application function:

db, err := kouten.Dial(ctx, []string{"127.0.0.1:17301"}, kouten.Options{})
if err != nil { return err }
defer db.Close()
id, err := db.PutJSON(ctx, "articles", map[string]string{"title": "Hello"})
if err != nil { return err }
var article map[string]string
found, err := db.GetJSON(ctx, id, &article)

Import kouten "github.com/puffball1567/koutendb-go" and pass a Go context. See the complete example and embedded setup and TLS, authentication and error handling.

PHP

The PHP driver offers native TCP using PHP streams, without ext-ffi or libkoutendb. Existing FFI APIs remain available and require ext-ffi only when that transport is selected. It is published on Packagist:

Install it in a Composer project:

composer require koutendb/koutendb:^0.2

Use KoutenDB::connectTcp() for native TCP; connect() retains its FFI behavior. See the PHP driver documentation for authentication, TLS and Laravel examples.

For FFI mode only, build the KoutenDB core shared library and point the driver at it:

scripts/build_capi.sh
export KOUTENDB_CORE_DIR=/path/to/koutendb

For local driver development from a checkout of koutendb-php, use the Docker smoke test:

KOUTENDB_CORE_DIR=/path/to/koutendb ./docker-test.sh

For Composer path development against a local koutendb-php checkout:

{
  "repositories": [
    { "type": "path", "url": "../koutendb-php" }
  ],
  "require": {
    "koutendb/koutendb": "*"
  }
}

Swift

The Swift driver is a SwiftPM wrapper over the C ABI. Linux smoke is Docker backed.

scripts/build_capi.sh
drivers/swift/docker-test.sh

Use a local package dependency:

.package(path: "../drivers/swift")

iOS/macOS packaging, sandbox paths, XCFramework packaging, and SwiftUI/UIKit integration are still future validation work.

C#

The C# driver is a generic .NET C ABI wrapper.

scripts/build_capi.sh
dotnet run --project drivers/csharp/ContractSmoke/ContractSmoke.csproj

Use a project reference until NuGet publication:

<ProjectReference Include="../drivers/csharp/KoutenDB/KoutenDB.csproj" />

Unity-specific lifecycle, editor tooling, and asset packaging are intentionally separate from this generic OSS driver.

C++

The C++ driver provides a C++17 C ABI wrapper and an optional native TCP target:

  • repository: puffball1567/koutendb-cpp v0.2.0
  • embedded: C++17 RAII wrapper over libkoutendb.so
  • native TCP: KoutenDB::tcp, without libkoutendb; requires Asio, OpenSSL, libsodium and nlohmann_json

For the C ABI examples:

git clone https://github.com/puffball1567/koutendb-cpp.git
cd koutendb-cpp
cmake -S . -B build -DKOUTENDB_CORE_DIR=/path/to/koutendb
cmake --build build
./build/koutendb_cpp_contract_smoke

For TCP-only setup, use -DKOUTENDB_CPP_BUILD_EXAMPLES=OFF -DKOUTENDB_CPP_BUILD_TCP=ON and follow the native TCP guide.

Unreal-specific module packaging, Blueprint bindings, editor tooling, and engine lifecycle integration are intentionally separate from this generic OSS driver.

Kotlin / JVM

The Kotlin driver is Kotlin-first and Java-compatible at the bytecode level. It uses a small JNI bridge over the C ABI.

scripts/build_capi.sh
drivers/kotlin/docker-test.sh

Maven Central publishing and Android packaging are future work.

Compatibility Suite

External native drivers share the protocol conformance harness: 27 scripted protocol cases and six authenticated/TLS real-server configurations. For example, build the Go adapter in the Go checkout, then run from the core checkout:

bash scripts/native_driver_conformance.sh /path/to/koutendb-go/bin/conformance

The commands below test the core’s in-tree foundations, not every external release.

Run non-Docker checks:

scripts/driver_compat.sh

Run Docker-backed PHP / Swift / Kotlin checks:

KOUTEN_COMPAT_DOCKER=1 scripts/driver_compat.sh

Skip wire checks when only C ABI and Docker wrapper checks are needed:

KOUTEN_COMPAT_DOCKER=1 KOUTEN_COMPAT_WIRE=0 scripts/driver_compat.sh