Quick Start

Get SochDB running in 5 minutes.

---

Prerequisites

Requirement	Version	Check Command
Python (optional)	3.9 or newer	python --version
Node.js (optional)	18 or newer	node --version
Go (optional)	1.24 or newer	go version
Rust (optional)	1.85 or newer, edition 2024	rustc --version
Git	Any recent	git --version

Current SDK versions: Python 0.5.9, Node.js 0.5.3, Go 0.4.5, Rust crate sochdb 2.0.3 (core engine 2.0.3).

---

Installation

Python

pip install sochdb

note

The PyPI name sochdb ships two importable packages: the pure-Python ctypes SDK (0.5.9, the broad embedded + server SDK used in these examples) and a native PyO3 engine (2.0.3, exposing HnswIndex/BM25Index/TableDatabase/etc.). The examples below use the 0.5.9 SDK's Database class.

Node.js / TypeScript

npm install @sochdb/sochdb

Go

go get github.com/sochdb/sochdb-go

note

The Go SDK is remote-first by default — a plain go get/go build compiles only the gRPC/remote client. The in-process embedded FFI engine is gated behind the sochdb_embedded build tag and requires the native library plus CGO. See the Go SDK guide for the embedded setup.

Rust

cargo add sochdb

Or add it to your Cargo.toml directly:

[dependencies]
sochdb = "2.0.3"

Build from Source

git clone https://github.com/sochdb/sochdb
cd sochdb
cargo build --release

note

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

---

Hello World

Each example opens an embedded database, writes a couple of keys, reads one back, then runs an atomic transaction.

Python

from sochdb import Database

# Open database (creates it automatically). Keys and values are bytes.
db = Database.open("./my_first_db")

# Store data
db.put(b"users/alice/name", b"Alice Smith")
db.put(b"users/alice/email", b"alice@example.com")

# Retrieve data
name = db.get(b"users/alice/name")
print(f"Name: {name.decode()}")  # Output: Name: Alice Smith

# Atomic transaction (auto-commits on clean exit, auto-aborts on exception).
# Transaction.commit() returns an HLC-backed monotonic commit timestamp.
with db.transaction() as txn:
    txn.put(b"users/bob/name", b"Bob Jones")
    txn.put(b"users/bob/email", b"bob@example.com")

db.close()

Node.js / TypeScript

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

// EmbeddedDatabase.open() is SYNCHRONOUS — no await. Keys/values are Buffers.
const db = Database.open('./my_first_db');

// Store data (auto-transaction wrappers are async)
await db.put(Buffer.from('users/alice/name'), Buffer.from('Alice Smith'));
await db.put(Buffer.from('users/alice/email'), Buffer.from('alice@example.com'));

// Retrieve data
const name = await db.get(Buffer.from('users/alice/name'));
console.log(`Name: ${name?.toString()}`);  // Output: Name: Alice Smith

// Atomic transaction. withTransaction auto-commits/auto-aborts.
// EmbeddedTransaction.commit() resolves to void.
await db.withTransaction(async (txn) => {
  await txn.put(Buffer.from('users/bob/name'), Buffer.from('Bob Jones'));
  await txn.put(Buffer.from('users/bob/email'), Buffer.from('bob@example.com'));
});

db.close();

Go

The default build is remote-first, so connect to a running SochDB gRPC server:

package main

import (
    "fmt"
    sochdb "github.com/sochdb/sochdb-go"
)

func main() {
    // Connect to a SochDB gRPC server (defaults to localhost:50051 if empty).
    client, err := sochdb.GrpcConnect("localhost:50051")
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // Store data
    if err := client.GrpcPut([]byte("users/alice/name"), []byte("Alice Smith"), "default", 0); err != nil {
        panic(err)
    }

    // Retrieve data
    name, found, err := client.GrpcGet([]byte("users/alice/name"), "default")
    if err != nil {
        panic(err)
    }
    if found {
        fmt.Printf("Name: %s\n", name) // Output: Name: Alice Smith
    }
}

Prefer an in-process database? Build with the embedded tag (go build -tags sochdb_embedded) and use the embedded package:

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

db, err := embedded.Open("./my_first_db")
if err != nil {
    panic(err)
}
defer db.Close()

db.Put([]byte("users/alice/name"), []byte("Alice Smith"))

// Atomic transaction. txn.Commit() returns error only.
err = db.WithTransaction(func(txn *embedded.Transaction) error {
    return txn.Put([]byte("users/bob/name"), []byte("Bob Jones"))
})

Rust

use sochdb::Connection;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connection is the durable, WAL-backed embedded database (aliased as Database).
    let conn = Connection::open("./my_first_db")?;

    // Writes run inside an implicit transaction that begins on the first
    // operation. Call commit_txn() to make them durable.
    conn.put(b"users/alice/name", b"Alice Smith")?;
    conn.put(b"users/alice/email", b"alice@example.com")?;
    conn.put_path("users/bob/name", b"Bob Jones")?; // path helper
    let ts = conn.commit_txn()?; // commit_txn() returns the commit timestamp
    println!("Committed at {ts}");

    // Retrieve data (reads also open an implicit read transaction).
    if let Some(name) = conn.get(b"users/alice/name")? {
        println!("Name: {}", String::from_utf8_lossy(&name));
    }

    // An explicit transaction groups several writes into one atomic commit.
    conn.begin_txn()?;
    conn.put(b"users/bob/email", b"bob@example.com")?;
    conn.commit_txn()?;

    Ok(())
}

---

Verify Installation

Python

python -c "import sochdb; print('SochDB Python SDK', sochdb.__version__)"

Node.js

node -e "const s = require('@sochdb/sochdb'); console.log('SochDB Node.js SDK', s.VERSION)"

Go

go list -m github.com/sochdb/sochdb-go

Rust

cargo build --release && echo "SochDB Rust SDK installed!"

---

Configuration

SochDB works out of the box with sensible defaults. For customization:

Environment Variables

# Enable debug logging (standard Rust env filter)
export RUST_LOG=sochdb=debug

# Point the Python FFI loader at a locally built native library
export SOCHDB_LIB_PATH=/path/to/sochdb/target/release

Durability Tuning

Rather than a config file, pass durability options when you open the database. Each SDK exposes the same underlying knobs (sync mode, group commit, index policy):

Python

The 0.5.9 SDK's Database.open takes a config dict with keys such as sync_mode ('off', 'normal', 'full'), wal_enabled, group_commit, and index_policy ('write_optimized', 'balanced', 'scan_optimized', 'append_only'):

from sochdb import Database

# Optimize for write throughput
db = Database.open("./my_first_db", config={
    "sync_mode": "normal",
    "group_commit": True,
    "index_policy": "write_optimized",
})

Node.js / TypeScript

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

// Full fsync on every commit, write-optimized index policy
const db = Database.open('./my_first_db', {
  syncMode: 'full',
  indexPolicy: 'write_optimized',
});

Rust

use sochdb::{Connection, ConnectionConfig};

// Defaults: group_commit=true, sync_mode=Full, ordered index on.
let conn = Connection::open_with_config(
    "./my_first_db",
    ConnectionConfig::throughput_optimized(),
)?;

---

Next Steps

Goal	Resource
Build a complete app	First App Tutorial
Learn vector search	Vector Search Tutorial
Use with LLM agents	MCP Integration
Understand internals	Architecture
Contribute	Contributing Guide

---

Troubleshooting

Common Issues

Python: ModuleNotFoundError: No module named 'sochdb'

pip install --upgrade sochdb

Rust: error: linking with 'cc' failed

Install build tools:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# Fedora
sudo dnf install gcc

Permission denied on Unix socket

The IPC server listens on a sochdb.sock socket inside the database directory. Unix sockets are not available on Windows. Fix permissions with:

chmod 755 ./my_first_db/sochdb.sock

Get Help

• GitHub Issues
• Documentation Home
• API Reference