ToonDB Documentation

Welcome to the official ToonDB documentation. ToonDB is The LLM-Native Database — a high-performance embedded database designed specifically for AI applications.

---

Key Features

Feature	Description
40-66% Fewer Tokens	TOON format optimized for LLM consumption
Namespace Isolation (v0.3.0)	Type-safe multi-tenancy with per-tenant data isolation
Hybrid Search (v0.3.0)	Vector + BM25 keyword search with RRF fusion
ContextQuery Builder (v0.3.0)	Token-aware retrieval with budgeting and deduplication
Blazing Fast	Rust-powered with zero-copy and SIMD
Vector Search	Built-in HNSW indexing for embeddings
Embeddable	In-process or client-server mode
Multi-Language	Native SDKs for Rust, Python, Node.js, Go
MCP Ready	Seamless Claude/LLM agent integration

---

Quick Install

Rust

cargo add toondb

use toondb::Database;

fn main() -> anyhow::Result<()> {
    let db = Database::open("./my_app_db")?;

    db.with_transaction(|txn| {
        txn.put(b"users/alice", br#"{"name": "Alice", "role": "admin"}"#)?;
        Ok(())
    })?;

    if let Some(user) = db.get(b"users/alice")? {
        println!("{}", String::from_utf8_lossy(&user));
    }

    Ok(())
}

Python

pip install toondb-client

from toondb import Database

db = Database.open("./my_app_db")

with db.transaction() as txn:
    txn.put(b"users/alice", b'{"name": "Alice", "role": "admin"}')

user = db.get(b"users/alice")
print(user.decode())  # {"name": "Alice", "role": "admin"}

db.close()

Node.js

npm install @sushanth/toondb

import { Database } from '@sushanth/toondb';

const db = await Database.open('./my_app_db');

await db.withTransaction(async (txn) => {
  await txn.put('users/alice', '{"name": "Alice", "role": "admin"}');
});

const user = await db.get('users/alice');
console.log(user?.toString());

await db.close();

Go

go get github.com/toondb/toondb-go

package main

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

func main() {
    db, _ := toondb.Open("./my_app_db")
    defer db.Close()

    db.WithTransaction(func(txn *toondb.Transaction) error {
        return txn.Put("users/alice", []byte(`{"name": "Alice", "role": "admin"}`))
    })

    user, _ := db.Get("users/alice")
    fmt.Println(string(user))
}

→ Full Quick Start Guide

---

Documentation Sections

🚀 Getting Started

Step-by-step guides to get you up and running quickly.

• Quick Start — 5-minute intro
• Installation — All platforms
• First App — Build something real

📖 Guides

Task-oriented guides for specific use cases.

Language SDKs:

• Rust SDK — Native Rust guide
• Python SDK — Complete Python guide
• Node.js SDK — TypeScript/JavaScript guide
• Go SDK — Go client guide

Features:

• SQL Guide — Working with SQL queries
• Vector Search — HNSW indexing
• Bulk Operations — Batch processing
• Deployment — Production setup

💡 Concepts

Deep dives into ToonDB's architecture and design.

• Architecture — System design
• TOON Format — Token-optimized format
• Performance — Optimization guide

📋 API Reference

Complete technical specifications.

• SQL API — SQL query reference
• Rust API — Crate documentation
• Python API — Full Python API docs
• Node.js API — TypeScript/JavaScript API
• Go API — Go package documentation

🛠️ Server Reference

Deep technical documentation for ToonDB servers and tools.

• IPC Server — Wire protocol & architecture
• gRPC Server — Vector search service
• Bulk Operations — High-performance tools

🍳 Cookbook

Recipes for common tasks.

• Vector Indexing — Embedding workflows
• MCP Integration — Claude integration
• Logging — Observability setup

---

Quick Links

I want to...	Go to...
Get started in 5 minutes	Quick Start
Use SQL queries	SQL Guide
Use the Rust SDK	Rust Guide
Use the Python SDK	Python Guide
Use the Node.js SDK	Node.js Guide
Use the Go SDK	Go Guide
Add vector search	Vector Search
Understand the architecture	Architecture
See the SQL API reference	SQL API

---

External Links

• toondb.dev — Main website
• GitHub — Source code
• Discussions — Community Q&A