TapirusDB Documentation

Overview & Design Philosophy #

Traditional software systems force engineers into Fragmented Polyglot Persistence. Building an intelligent application or AI agent routinely requires orchestrating four disparate database daemons: PostgreSQL for structured tables, Pinecone or Qdrant for vector embeddings, Neo4j for relationship graphs, and MongoDB for schemaless documents.

This "Frankenstack" introduces severe network socket serialization overhead (40–90 ms roundtrips), heavy memory consumption (> 2 GB idle RAM), synchronization drift, and operational fragility.

Core Tenets

• 100% Safe Rust: Zero unsafe code blocks. Protected at compile-time against memory corruption, dangling pointers, buffer overflows, and use-after-free vulnerabilities.
• Single File Atomic Storage: The entire database resides in a single, robust .tapir binary file protected by ChaCha20-Poly1305 AEAD authenticated page encryption.
• Micro-Footprint: Consumes less than 4 MB of idle RAM, making it optimal for robotics, mobile applications, edge silicon, and serverless containers.
• Zero Cloud Lock-in: Fully sovereign and self-contained. Runs anywhere from an air-gapped embedded device to massive cloud microservices.

Why TapirusDB (Kill the Frankenstack) #

Observe the architectural contrast between traditional multi-database deployments and TapirusDB's unified in-process model:

Installation & Ecosystem Packages #

TapirusDB provides first-class native distribution across all major programming ecosystems and operating system package managers.

Package Managers (Terminal CLI)

brew install https://raw.githubusercontent.com/tapiruslab/TapirusDB/main/Formula/tapirus.rb

winget install --manifest https://raw.githubusercontent.com/tapiruslab/TapirusDB/main/winget/tapirus.yaml

curl -fsSL https://raw.githubusercontent.com/tapiruslab/TapirusDB/main/install.sh | bash

Language Client Libraries

30-Second Quickstart #

Initialize an in-memory or encrypted single-file database, create structured tables with vector columns, execute graph traversals, and query via SQL in under 30 seconds:

use tapirus::{Connection, DistanceMetric, Result};
use serde_json::json;

fn main() -> Result<()> {
    // 1. Open or create encrypted database file
    let db = Connection::open("production.tapir")?;

    // 2. Relational SQL Table with native Vector column
    db.execute("
        CREATE TABLE documents (
            id INTEGER PRIMARY KEY,
            title TEXT NOT NULL,
            embedding VECTOR(4)
        );
    ")?;

    // 3. Insert record with 4-dimensional vector
    db.execute("
        INSERT INTO documents (id, title, embedding)
        VALUES (1, 'Safe Systems Architecture', [0.12, 0.45, 0.88, -0.23]);
    ")?;

    // 4. Property Graph Node & Edge (GraphRAG)
    db.graph_add_node(1, "Author", r#"{"name":"Faiz"}"#)?;
    db.graph_add_node(2, "Concept", r#"{"name":"Quad-Model"}"#)?;
    db.graph_add_edge(1, 2, "INVENTED", 1.0, "")?;

    // 5. Query relational records via SQL
    let rows = db.query("SELECT id, title FROM documents WHERE id = 1;")?;
    println!("Retrieved: {:?}", rows);

    Ok(())
}

Interactive SLM Studio (Live Demo) #

Experience TapirusDB's multi-model execution engine live in your web browser. Switch between SQL, Vector Cosine similarity math, Graph traversal, and Agent Memory fusion:

1. Relational SQL-92 Engine #

TapirusDB embeds a full ANSI SQL-92 query engine supporting standard DDL, DML, composite primary keys, B+Tree indexes, and ACID transactions.

-- Create structured table with constraints
CREATE TABLE accounts (
    id INTEGER PRIMARY KEY,
    username TEXT NOT NULL UNIQUE,
    balance REAL DEFAULT 0.0,
    created_at TIMESTAMP
);

-- Insert records
INSERT INTO accounts (id, username, balance) VALUES (101, 'alex_ai', 1450.50);
INSERT INTO accounts (id, username, balance) VALUES (102, 'sarah_dev', 3200.00);

-- Filtered queries with aggregations
SELECT username, balance 
FROM accounts 
WHERE balance > 1000.0 
ORDER BY balance DESC;

2. Native HNSW Vector Search #

Unlike external vector databases requiring network roundtrips, TapirusDB supports native VECTOR(N) columns directly inside tables. It utilizes Hierarchical Navigable Small World (HNSW) graphs and Inverted File (IVF) indexes, accelerated by SIMD AVX-512, AVX2, and ARM NEON intrinsics.

-- Define table with 1536-dimensional embeddings (OpenAI / Gemini embedding format)
CREATE TABLE embeddings (
    doc_id INTEGER PRIMARY KEY,
    content TEXT,
    vector VECTOR(1536)
);

-- Query top-5 nearest neighbors using Cosine Similarity
SELECT doc_id, content, VECTOR_COSINE(vector, [0.012, -0.045, ...]) AS score
FROM embeddings
ORDER BY score DESC
LIMIT 5;

3. Knowledge Graph & GraphRAG #

TapirusDB implements native property graph storage using Compressed Sparse Row (CSR) adjacency arrays. Query relationships declaratively using the industry-standard openCypher language:

// 1. Add nodes and relationships
CREATE (p:Person {name: "Ada Lovelace", role: "Mathematician"})
CREATE (c:Concept {name: "Analytical Engine"})
CREATE (p)-[:PIONEERED {year: 1843}]->(c);

// 2. Multihop graph traversal pattern matching
MATCH (p:Person)-[r:PIONEERED]->(c:Concept)
WHERE c.name = "Analytical Engine"
RETURN p.name, r.year, c.name;

4. Schema-less JSON Document Collections #

When structured schemas are too rigid, store arbitrary nested JSON documents with sub-millisecond document ID retrieval and JSONPath indexing:

from tapirus import Connection

db = Connection.open("app.tapir")
users = db.collection("users")

# Insert nested JSON payload
user_id = users.insert_one({
    "name": "Faiz",
    "telemetry": {
        "status": "active",
        "tokens": 4500,
        "models": ["phi-3", "llama-3"]
    }
})

# Find document
doc = users.find_one({"_id": user_id})
print(doc)

Storage Architecture: The .tapir Format #

TapirusDB stores all tables, vector trees, graph topologies, and JSON collections inside a single, self-describing binary file with the extension .tapir:

• 4KB Slotted Pages: Ultra-fast zero-copy disk serialization aligned to modern NVMe SSD physical page boundaries.
• Page-Level ChaCha20-Poly1305 AEAD: Cryptographically verified against disk tampering with constant-time Key Check Value (KCV) verification.
• Atomic WAL & Multi-Version Concurrency (MVCC): Readers never block writers, and writes are guaranteed crash-safe via Write-Ahead Logging (WAL).

Client SDK Guides #

Python SDK Guide

import tapirus

# Connect to database file
db = tapirus.Connection("memory.tapir")

# Execute DDL
db.execute("CREATE TABLE agents (id INT PRIMARY KEY, name TEXT);")
db.execute("INSERT INTO agents VALUES (1, 'Hermes-Agent');")

# Query rows
results = db.query("SELECT * FROM agents;")
for row in results:
    print(row["id"], row["name"])

Node.js & TypeScript SDK Guide

import { Tapirus } from "tapirus";

const db = new Tapirus("production.tapir");

// Query JSON
const rows = db.query("SELECT * FROM users WHERE active = 1;");
console.log(rows);

Go (Golang) SDK Guide

Official Go client library for TapirusDB. View package reference and source documentation on pkg.go.dev.

package main

import (
    "context"
    "fmt"
    tapirus "github.com/tapiruslab/TapirusDB/sdks/go"
)

func main() {
    client := tapirus.NewClient(tapirus.Config{Endpoint: "http://127.0.0.1:8080"})
    res, _ := client.Query(context.Background(), "SELECT * FROM items;")
    fmt.Println(res)
}

Model Context Protocol (MCP) Server #

TapirusDB natively integrates with AI coding assistants (Claude Desktop, Cursor, Gemini) via the open Model Context Protocol (MCP):

{
  "mcpServers": {
    "tapirus": {
      "command": "tapirus",
      "args": ["mcp", "--database", "C:/path/to/database.tapir"]
    }
  }
}