KoutenDB Driver Installation Guide

This document shows the current technical-preview setup for each language. The English README and this file are the canonical driver installation references.

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, and Python drivers are also published as language-native packages. Other non-Nim drivers are still repository-local foundations, so those examples assume a local clone of this repository.

Optional FAISS Setup

The exact vector backend works without FAISS. For the FAISS bridge path, fetch and build FAISS after cloning:

scripts/fetch_faiss.sh
scripts/setup_faiss_toolchain.sh   # only needed when system CMake is too old
scripts/build_faiss_bridge.sh
kouten doctor

By default, scripts/fetch_faiss.sh fetches the configured FAISS tag and records the actual commit in third_party/faiss.version. To pin an exact commit for a reproducible build, set KOUTEN_FAISS_COMMIT. See faiss-versioning.md.

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 --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

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.

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.

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 is published as a C ABI wrapper:

Install it in a Rust project:

cargo add koutendb

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

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

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 a C ABI wrapper.

scripts/build_capi.sh
cd drivers/go
GOCACHE="${GOCACHE:-/tmp/kouten-go-cache}" go test ./...

Use a local module replace until publication:

replace github.com/koutendb/koutendb-go => ../drivers/go

PHP

The PHP driver uses FFI over the C ABI. Local PHP must have ext-ffi enabled. It is published on Packagist:

Install it in a Composer project:

composer require koutendb/koutendb:^0.1

Build the KoutenDB core shared library first and point the PHP 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 is released as a separate C++17 wrapper over the C ABI:

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

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

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