Build with what the engine actually does.

Overview

The default Rust tapirus engine stores relational tables, vectors, graph data and JSON documents in one process. AI document memory combines indexed lexical retrieval, supplied embeddings, recency and importance. An application can use the models together, but each API has its own supported syntax and limits.

Architecture and workload fit

The in-process design removes a network hop when the application and database run together. It can simplify local applications that need SQL rows and cited AI source retrieval in the same transaction. It is strongest when the application owns its local data and can validate the supported SQL and file behavior against its workload.

For independent transaction ownership, use SessionDatabase. The ordinary ConnectionPool::acquire() clones a shared connection and does not create separate concurrent SQL sessions. See embedded workflows.

Installation and version provenance

GitHub release v1.0.2 is the native engine release. Choose the archive for your operating system and architecture, then verify its published SHA-256 sidecar. The release inventory has separate CLI, FFI and edition assets; inspect the exact file before installing.

These are dated observations, not a live registry feed. The public @tapirus/db npm package is a legacy artifact; use tapirus for new Node.js installations. The downloads page lists browser Lite and Windows Studio separately. The Windows Studio 0.1.3 installer is a different product/version from the engine 1.0.2 release.

Rust quickstart

Use the version actually available on crates.io, or pin the v1.0.2 release source. This example exercises the supported core SQL API.

use tapirus::{Connection, Result};

fn main() -> Result<()> {
    let db = Connection::open("notes.tapir")?;
    db.execute("CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT NOT NULL)")?;
    db.execute("INSERT INTO notes (id, body) VALUES (1, 'Check recovery')")?;
    let rows = db.query("SELECT id, body FROM notes")?;
    println!("{rows:?}");
    db.close()?;
    Ok(())
}

Use bound parameters for user input. Test reopen, rollback and backup behavior before handling important data. See the API cookbook.

Browser and desktop Studio

Studio Lite runs the actual Rust WASM engine for SQL, AI document memory and TAP heuristic operations. It stores committed snapshots in IndexedDB and opens or downloads native .tapir files. The Lite ZIP includes the WASM module and a local Python HTTP launcher for offline use.

The Windows Studio 0.1.3 desktop installer is separate. The desktop training interface requires a local Python training backend, model weights and dependencies; the published installer does not bundle a complete training service. No browser model training is claimed.

There is no embedded simulated query console on this documentation page. The workspace link above is the executable demo.

SQL and transactions

TapirusDB supports a documented SQL subset with DDL, DML, query operations, bound parameters and transactions. It is not full ANSI SQL-92 or a drop-in SQLite replacement. Check parser behavior for the exact statements an application needs.

CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT NOT NULL);
INSERT INTO notes (id, body) VALUES (1, 'Check recovery');
SELECT id, body FROM notes;

Execute the three statements separately in the browser workspace. BEGIN, COMMIT, ROLLBACK and savepoints also cover supported AI memory changes. SQL access is serialized; there is no snapshot-isolated MVCC.

Vector search and AI memory

The engine has fixed-dimension vector storage and HNSW search. AI memory can combine BM25 keywords with application-supplied embeddings and return original source text plus score components. It does not generate embeddings unless the application provides a separate model or provider.

Use the same embedding model and dimensions for documents and queries. combined_score ranks results; it is not a probability or a measure of factual truth. Retrieval quality and HNSW recall need a labeled evaluation for your corpus. See AI memory contract.

Graph APIs and query subset

The graph module supports nodes, edges, neighbors, paths and selected graph algorithms. The parser accepts a bounded GRAPH MATCH and Cypher MATCH/CREATE subset. It does not claim full openCypher or GraphBLAS conformance. CSR conversion is available, but not every query runs over a persistent CSR index.

See the implementation notes for syntax boundaries.

JSON documents

JSON document collections are available in the default Quad engine and the Document edition. Supported indexing, filters and update behavior are defined by the collection API and its tests. No BSON compatibility is claimed. See the edition guide and cookbook.

TAP decision functions

TAP provides local classification, scoring, verification and routing functions in Rust, SQL and WASM. The default weights are deterministic generated baseline weights; the default behavior combines similarity and lexical heuristics. A separate serialized model can be loaded, but a trained model is not bundled with these default weights.

SELECT id, TAP_CLASSIFY(body, 'billing, technical, sales') AS category
FROM tickets;

For browser inference, use Studio Lite. Model training belongs to a separate local desktop backend and must be tested with a real labeled dataset before making accuracy claims.

The .tapir file and WAL

The engine uses a 4 KB page format and a write-ahead log for commits and recovery. A native .tapir file can be opened by the Rust WASM workspace when it uses a compatible format and is within browser limits. Keep a backup before moving files between editions or versions.

WAL and file contents are not automatically encrypted. Read the recovery notes and test power-loss and restore paths for your deployment.

Memory, footprint and concurrency

The engine uses in-process structures and page caching. Memory, executable size and latency depend on build flags, corpus, index size and workload. We do not publish a universal idle RAM figure. Feature profiles are API boundaries, not proof of a tiny binary or a security sandbox.

SQL sessions serialize access; ConnectionPool::acquire() shares connection state. For a constrained device, measure peak RSS, allocator behavior, file I/O and reopen time on the actual hardware. The separate Micro component targets bounded bare-metal flash records and has a different scope from Quad.

Security and encryption boundary

The main tapirus crate forbids explicit unsafe Rust. The separate C FFI boundary contains unsafe code, and dependency code is outside that crate lint. Memory safety is one property; it is not a guarantee of correct SQL, crash safety, constant memory, or absence of vulnerabilities.

Native page encryption is optional. Encrypted pages use XChaCha20-Poly1305 with 256-bit keys and 24-byte nonces; passphrases use PBKDF2-HMAC-SHA256. The format header exposes opening metadata. Current key storage is not guaranteed to zeroize on drop. Browser workspace copies are unencrypted. See security policy and limits.

Rust SDK

The embedded tapirus crate exposes Connection and the model APIs. Check the registry version before choosing a dependency version. The cookbook has transaction, parameter binding and model examples. The core license is BUSL-1.1; review LICENSE for use terms.

Python SDK

The PyPI package is a native binding and requires Python 3.10+. The public package can lag the repository source. The SDK packaging declares MIT AND BUSL-1.1, reflecting the wrapper and core boundary.

import tapirus

with tapirus.connect("assistant.tapir") as db:
    db.store_memory({"content": "Maintenance is due after 500 hours.",
                     "namespace": "manuals"})
    print(db.search_memories({"query": "maintenance interval",
                              "namespace": "manuals"}))

See the Python SDK guide for the exact installed version's API and platform wheels.

Node.js and TypeScript SDK

The npm package uses a native addon and targets Node.js 22+. Match the published native binary to the target OS and architecture. Source packaging declares MIT AND BUSL-1.1.

const { open } = require('tapirus');
const db = open('assistant.tapir');
db.storeMemory({ content: 'Maintenance is due after 500 hours.',
                 namespace: 'manuals' });
const sources = db.searchMemories({ query: 'maintenance interval',
                                    namespace: 'manuals', limit: 5 });
console.log(sources.map(source => source.entry.content));
db.close();

Verify behavior against the Node SDK guide for the package version you install.

Go client

The Go SDK is an HTTP client for tapirus serve. It is not an embedded Go database. It supports bound SQL parameters and typed response handling; deploy and secure a matching daemon separately. Check the Go module version and client guide.

PHP client

The Composer package uses HTTP to reach tapirus serve. It requires PHP 8+, cURL and JSON. It does not bundle the Rust engine. Read the PHP client guide and test against the exact daemon version.

HTTP server

tapirus serve uses a synchronous TCP listener with a bounded number of client threads; SQL operations share a locked connection. This is a simple HTTP interface, not an asynchronous, horizontally scalable database server. GET /health is public by design; SQL and chat routes check an API key when one is configured.

tapirus serve --host 127.0.0.1 --port 3005 app.tapir

Set TAPIRUS_API_KEY in the process environment for protected endpoints. Send it using Authorization: Bearer … or X-API-Key; keep secrets out of command history and URL query strings. New source requires a key for non-loopback binds and bounds request headers and bodies, client count and read time. Published v1.0.2 binaries predate that source change until a new validated release is built.

Import and CLI

The CLI supports SQL execution and import commands for CSV, JSONL, JSON and Markdown. Import schemas and modes differ by format. Run tapirus import --help and use the cookbook before importing production data. Check row counts and reopen the file after a test import.

MCP stdio server

tapirus mcp app.tapir exposes a JSON-RPC 2.0 stdio server for compatible MCP clients. It uses the local file permissions and the permissions of the launching process. Inspect the advertised tools and restrict the database path for each integration. Use tapirus mcp --help for current options.

WASM browser workspace and edge status

The deployed Rust browser workspace includes a 1,684,746-byte WASM module in the current site build. It initializes generated JavaScript glue, runs the database in the browser and saves committed snapshots in IndexedDB. The downloadable Lite ZIP packages this workspace and can be served locally.

Use bound parameter APIs such as execute_params or query_params_json for external data. Never interpolate request headers into SQL text. See the WASM build and test guide.

Edition builds

SQL Lite, Document, Graph, Vector and Quad have first-party binaries. Editions restrict exposed operations but share core storage code and are not security sandboxes. The same file format can be opened across supported editions; back up important files before switching. No fixed RAM or binary size is promised.

cargo build --release -p tapirus --no-default-features --features lite --bin tapirus-lite

See build commands and limits for all entry points and platform checks.

Performance evidence

Earlier latency, RAM, binary-size and competitor speed figures were withdrawn after the benchmark audit. They are not specifications. The release validation record contains a corrected small-workload Windows snapshot with checked query results, database reopen, comparable SQLite WAL durability and HNSW recall. It reports both faster reads and slower writes in that fixture.

Run cargo bench --bench release_readiness --offline from a checked-out engine source revision. The resulting local report is evidence for that revision and host, not a universal performance promise.

Capability matrix

Found a mismatch between a statement here and the current source? Open an issue with the section link, source commit and a minimal reproduction on the engine issue tracker.