Installation

Complete installation guide for SochDB across the language SDKs and the standalone server binary.

Component versions

SochDB ships as a Rust core engine plus four language SDKs, each versioned independently.

Component	Version	Install	Minimum toolchain
Core engine (Rust crate sochdb)	2.0.3	cargo add sochdb	Rust 1.85+ (2024 edition)
Python SDK	0.5.9	pip install sochdb	Python 3.9+
Node.js SDK	0.5.3	npm install @sochdb/sochdb	Node.js 18+
Go SDK	0.4.5	go get github.com/sochdb/sochdb-go	Go 1.24

License split

The licensing differs by component:

• The core engine — the Rust workspace (the sochdb crate, the gRPC server, and the MCP server) — is AGPL-3.0-or-later, with commercial licensing available.
• The language SDKs (Python, Node.js, Go) are Apache-2.0.

Choose the SDK that matches your distribution requirements; the AGPL terms apply to the engine, not to the Apache-2.0 SDK packages.

---

Python SDK

pip install sochdb

Requires Python 3.9 or later. Pre-built wheels are available for Linux (x86_64), macOS (Apple Silicon), and Windows (x86_64); the bundled native libraries mean most users do not need a Rust toolchain.

Two packages named sochdb

There are two importable Python packages that both go by sochdb:

• The pure-Python ctypes SDK (v0.5.9, installed by pip install sochdb) — the broad embedded + server SDK with Database, Namespace, Collection, Queue, AgentMemory, temporal-graph, semantic-cache, and StudioClient. Use this for general application code.
• The PyO3 native engine (v2.0.3) — a lower-level extension exposing HnswIndex, BM25Index, RRFFusion, ThreeLaneHybridIndex, MultiShardHnswIndex, TableDatabase, the build_index* helpers, and recommended_hnsw_params.

Examples on this site use the 0.5.9 SDK unless noted otherwise.

Verify installation

from sochdb import Database

# Embedded mode: pass a local path (or ":memory:")
db = Database.open("./test_db")
db.put(b"test", b"hello")
value = db.get(b"test")
print(f"SochDB installed! Value: {value.decode()}")
db.close()

To connect to a running server instead of an embedded file, use the gRPC client with a host:port string:

from sochdb import SochDBClient

with SochDBClient("localhost:50051") as client:
    client.put(b"test", b"hello")
    print(client.get(b"test"))

---

Node.js / TypeScript SDK

npm install @sochdb/sochdb

Requires Node.js 18 or later.

Verify installation

import { EmbeddedDatabase } from '@sochdb/sochdb';

// EmbeddedDatabase.open() is synchronous
const db = EmbeddedDatabase.open('./test_db');
await db.put(Buffer.from('test'), Buffer.from('hello'));
const value = await db.get(Buffer.from('test'));
console.log(`SochDB installed! Value: ${value?.toString()}`);
await db.close();

note

EmbeddedDatabase.open() returns synchronously, and commit() resolves to Promise<void>. The Node SDK does not ship a routing module.

---

Go SDK

The Go SDK is remote-first by default: it talks to a running sochdb-grpc-server (or an IPC socket). The in-process embedded FFI engine is gated behind the sochdb_embedded build tag.

go get github.com/sochdb/sochdb-go

Requires Go 1.24.

Verify installation (remote / gRPC)

package main

import (
    "fmt"
    "log"

    sochdb "github.com/sochdb/sochdb-go"
)

func main() {
    // Connect to a running sochdb-grpc-server
    client, err := sochdb.GrpcConnect("localhost:50051")
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    fmt.Println("SochDB Go SDK installed!")
}

Embedded mode (build tag)

To use the in-process embedded engine, build with the sochdb_embedded tag and the embedded subpackage. This path links the native library, so you also need the SochDB native lib installed and pkg-config available.

go build -tags sochdb_embedded ./...

import "github.com/sochdb/sochdb-go/embedded"

db, err := embedded.OpenConcurrent("./test_db")

---

Rust crate

Add the core crate to your Cargo.toml. The current published version is 2.0.3.

cargo add sochdb

[dependencies]
sochdb = "2.0.3"

info

The sochdb crate is the core engine and is licensed AGPL-3.0-or-later (commercial licensing available). It requires Rust 1.85+ (2024 edition).

Verify installation

use sochdb::Database;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Database::open("./test_db")?;

    db.put(b"test", b"hello")?;
    if let Some(value) = db.get(b"test")? {
        println!("SochDB installed! Value: {}", String::from_utf8_lossy(&value));
    }
    Ok(())
}

---

Server binary (sochdb-grpc-server)

For multi-client and multi-language deployments, run the standalone server. It exposes gRPC plus optional WebSocket, Prometheus metrics, and a PostgreSQL wire endpoint.

Build from source

git clone https://github.com/sochdb/sochdb
cd sochdb

# Build the release binary (requires protobuf-compiler and cmake)
cargo build --release --package sochdb-grpc

# Binary lands at target/release/sochdb-grpc-server
./target/release/sochdb-grpc-server --host 0.0.0.0 --port 50051

Building from source needs Rust 1.85+, plus protobuf-compiler and cmake on the build host.

Run via Docker

docker run -p 50051:50051 sochdb/sochdb-grpc:latest

The image runs as a non-root sochdb user with its data directory at /var/lib/sochdb. The default command is --host 0.0.0.0 --port 50051; map additional ports (below) if you enable the WebSocket, metrics, or PG-wire endpoints.

Key CLI flags and default ports

All flags are parsed by clap; there is no --config file flag.

Flag	Default	Purpose
--host	127.0.0.1	Bind address
-p, --port	50051	gRPC port
--metrics-port	9090	Prometheus HTTP /metrics port (0 disables)
--ws-port	8080	WebSocket gateway port (0 disables)
--pg-port	5433	PostgreSQL wire protocol port (0 disables)
-d, --debug	off	Debug logging
--auth	off	Enable gRPC authentication
--api-key	none	Register an API key (env SOCHDB_API_KEY; requires --auth)
--tls-cert / --tls-key	none	Enable TLS (PEM paths; env SOCHDB_TLS_CERT / SOCHDB_TLS_KEY)
--tls-ca	none	CA cert for mTLS client verification (env SOCHDB_TLS_CA)
--secrets-path	none	Kubernetes Secrets mount path (env SOCHDB_SECRETS_PATH)
--pg-data-dir	none	Persistent directory for real SQL via PG-wire (env SOCHDB_PG_DATA_DIR)

Default port summary:

Service	Default port
gRPC	50051
Prometheus metrics (HTTP /metrics)	9090
WebSocket gateway	8080
PostgreSQL wire	5433

PostgreSQL wire endpoint

The PG-wire endpoint is simple-query only with no authentication and no TLS (cleartext). Keep it on loopback unless you explicitly accept the risk; the server logs a warning if --host is non-loopback. Without --pg-data-dir the endpoint only echoes queries — pass --pg-data-dir DIR (a directory path) to run real SQL (SELECT/INSERT/UPDATE/DELETE/DDL, including JOINs).

At-rest encryption

At-rest encryption (AES-256-GCM-SIV) exists as a library API but is not yet wired to a server CLI flag — sochdb-grpc-server does not currently construct an encryption engine. Treat it as available API / planned wiring, not a runtime toggle.

---

Build Python bindings from source

Most users should pip install sochdb. If you are modifying the Rust core, build the bindings locally:

cd sochdb-python-sdk

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install the package (editable)
pip install -e .

The build uses setuptools-rust, so a Rust toolchain (cargo) is required when building from source.

---

Platform-specific notes

macOS

On Apple Silicon Macs, ensure you are using a native ARM64 Python:

# Check architecture
python -c "import platform; print(platform.machine())"
# Should output: arm64

Linux

For best performance, ensure your kernel supports io_uring:

# Check kernel version (5.1+ recommended)
uname -r

Windows

Use PowerShell or Windows Terminal for the best experience:

pip install sochdb

---

Next steps

• Quick Start Guide — Your first SochDB application
• Python SDK Guide — Complete Python tutorial
• Vector Search — HNSW indexing guide