TapirusDB
TapirusDB is an embedded Rust database for local applications that need SQL, vector search and AI document memory in one runtime. Store text and embeddings, retrieve sources for an LLM, and keep SQL and memory changes in the same transaction.
Build local AI products with a data layer that runs inside your application. Start with the web tutorials, explore the API cookbook, or try the Rust browser workspace.
The default branch includes storage corrections, transactional AI memory and native SDK integration coverage. Published release archives may predate these changes; see release validation for evidence and the distinction between current source and published packages.
Highlights
- Local, in-process database with a
.tapirfile and a write-ahead log. - SQL support is a documented subset; TapirusDB is not a SQLite drop-in or a claim of full SQL conformance.
- Vector, graph, and JSON document APIs are available alongside relational tables.
- AI source retrieval combines BM25, supplied embeddings, recency and importance, with namespace/session filters and source citations.
- Indexed memory adds model-specific HNSW, upsert, revision checks, atomic batches, source versions, TTL and configurable budgets. Python tools provide verified SQLite scalar migration, document ingestion and retrieval evaluation. See AI and embedded workflows.
SessionDatabaseprovides independent transaction ownership over serialized access. The separate Micro component targets bounded bare-metal flash records.- The offline IoT capsule bridge exports a committed Micro slot without allocation and imports it into Quad's local AI memory with sequence/replay checks. A gateway may attach embeddings from a pinned local provider. It is a source-build capability, not a claim of signed device identity or on-chip LLM inference.
- The Rust WASM workspace opens and exports native
.tapirfiles and saves committed browser snapshots to IndexedDB. - First-party SQL Lite, Document, Graph and Vector entry points can be built separately; the default Quad engine exposes every model in the same native file. See edition builds and limits.
- Page encryption is optional. Review key handling and deployment configuration for your threat model.
- The main
tapiruscrate forbids explicit unsafe Rust. The C ABI crate contains unsafe boundary code. This does not prove functional correctness, crash safety, or bounded resource use. - Current source binds
tapirus serveto loopback by default, requires an API key for a non-loopback bind, and disables cross-origin CORS headers unless allowlisted via--cors-origin/TAPIRUS_CORS_ORIGIN. It limits service to 64 simultaneous clients, 16 KiB headers, 4 MiB bodies and a 10-second request read deadline. It accepts API keys in headers, not URL query strings. Pre-v1.0.4 release binaries may predate this source change; validate the exact downloaded release before relying on these limits in an executable. - Current source bounds serialized TAP model loads to 128 MiB and rejects inconsistent dimensions and non-finite weights. Default TAP weights are deterministic heuristic baseline weights, not trained or probability-calibrated models.
Rust quickstart
Need only one model? Build tapirus-lite, tapirus-document, tapirus-graph,
or tapirus-vector from the current source. Quad remains the default tapirus
binary. For example, a SQL-only CLI build is:
The edition binaries share the .tapir format, but they are API boundaries,
not security sandboxes or proven low-memory builds. Check the asset list for
the exact published release before depending on a prebuilt edition binary.
Follow the choose-an-edition tutorial
for a file-interchange walkthrough.
Add the crate to a Rust project, then open a database and use the SQL API:
use ;
Use parameterized APIs for user-provided values. Review the SQL parser and executor for the supported syntax and constraints before depending on a query shape.
Architecture and workload fit
TapirusDB is intended for local, single-process workloads that benefit from colocated relational, vector, graph, or document data. Its API and query support should be evaluated against the application requirements.
ConnectionPool::acquire() currently returns a clone of the same connection. Handles share session and transaction state; this is not a pool of independent database sessions. SQL execution uses shared locks, so the pool name does not imply concurrent SQL readers.
Use SessionDatabase when transactions need independent owners. Other sessions
return Busy or wait until the owning session finishes; access remains serialized.
WAL recovery, replication, backups, vector snapshots, HTTP behavior, and SDK bindings have regression tests for selected cases. Tests cover only the scenarios they exercise. Validate crash recovery, resource use, backup and restore, and SDK behavior on the target platform before storing important data.
AI document memory
const = require;
const db = ;
db.;
const sources = db.;
console.log;
db.;
Supply an embedding from your chosen model to add vector similarity. These methods run locally and participate in SQL transactions. See the AI memory guide for Rust, Node.js, score definitions and browser use.
HTTP server
tapirus serve exposes plaintext HTTP endpoints on 127.0.0.1:3005 by default. Set --api-key (or TAPIRUS_API_KEY) whenever reachable by untrusted callers, restrict CORS with --cors-origin / TAPIRUS_CORS_ORIGIN (disabled by default; same-origin only), and always place tapirus serve behind a TLS-terminating reverse proxy (Nginx, Caddy, Envoy, or Cloudflare Tunnel) before exposing it beyond loopback. See SECURITY.md for deployment limits and TLS reverse-proxy setup. The browser /chat page is public; /api/chat and /api/chat/logs require the configured API key.
Security, performance, and formal methods
- See SECURITY.md for the threat boundary, optional encryption, and reporting guidance.
- Historical latency, throughput, RAM, and binary-size figures are withdrawn pending corrected, reproducible measurements. See Benchmark status.
- TLA+ files describe selected WAL transitions. The repository has no TLC run output or refinement proof connecting the model to Rust; see the model scope.
- No ISO 26262, IEC 62304, DO-178C, or other functional-safety certification is claimed.
Build and test
These commands validate the current host build and exercised tests. They do not establish formal verification, certification, or correctness for every failure mode.
For a local Linux container build, run docker build -t tapirusdb:local .. The image runs as a non-root user. Mount a named volume at /data for data that must survive container removal, for example docker run --rm --network none --mount source=tapirus-demo,target=/data tapirusdb:local /data/demo.tapir -c "CREATE TABLE notes (id INTEGER)". A bind-mounted host directory must be writable by the container user. The local Windows Docker smoke check is powershell -NoProfile -File scripts/test-docker-smoke.ps1; it builds a local test image and verifies SQL reopen and error exit status. This local check is not a substitute for public release asset verification or cross-platform CI results.
Documentation
- Editions and build commands
- Offline Micro-to-Quad IoT capsules
- Choose an edition tutorial
- API cookbook
- WAL and recovery architecture notes
- TLA+ model scope
- Assurance scope and limitations
- SDKs
- Stack support, versions and package validation
- Current release and registry status
- Transactional AI memory
- Panduan TAP: browser, CLI, Rust dan Model Forge
- Release validation and packaging
Benchmark status
The audit found benchmark cases that need correction or clearer scope, including operations whose results may be optimized away, a dot-product case labeled as cosine, extrapolated vector-memory estimates, and comparisons with different durability settings. Do not use historical performance figures as product claims.
The corrected cargo bench --bench release_readiness harness checks results, reopens both databases and measures HNSW recall against exact neighbors. Its small-workload local results and limitations are recorded in release validation. Publish the source revision, binary hash, compiler flags, hardware, storage settings, dataset, warm or cold state, and latency distribution with every result.
TLA+ model scope
The repository contains a TLA+ model of selected WAL and recovery transitions. There is no TLC run output or refinement proof connecting the model to the Rust implementation. The model is a design artifact, not evidence that the compiled engine is formally verified.