Skip to content

Storage Adapters

ValtheraDB uses pluggable storage engines. Adapters fall into two classes:

  • CRUD - the full ActionsBase interface, named db-storage-<name>.
  • Specialized - non-document data models, named db-spec-<name>.

Quick Start: VDB() API

The easiest way to use adapters - auto-resolves based on config or env vars.

bun add @wxn0brp/db-resolver @wxn0brp/db-core

import { VDB } from "@wxn0brp/db-resolver";

// Dir adapter (default)
const db = VDB().dir("./data");

// SQLite with Bun
const db = VDB().sqlite.bun("db.sqlite");

// MongoDB
const db = VDB().mongodb("mongodb://localhost:27017", "mydb");

// Typed collections
const db = VDB<{ users: { id: number; name: string } }>().dir("./data");
await db.users.add({ id: 1, name: "Ala" });

Resolution order: force option -> VALTHERA_<NAME> env var -> def fallback -> ./vdb-data/<name>

In development, missing adapters are auto-installed.

Short names resolve to first-party @wxn0brp/db-storage-* packages. Third-party adapters are referenced by their full id (@scope/db-storage-<name>:<variant>); see Publishing.

-> Full Resolver Docs

Manual Installation

To use an adapter manually, install the package and create an instance.

Adapter Storage Install Repo
dir Directory of JSON5/JSON/YAML files bun add @wxn0brp/db-storage-dir GitHub
dir-index Directory storage with BTree index files (.idx) for binary-search queries bun add @wxn0brp/db-storage-dir-index GitHub
sqlite SQLite (Bun/Node/better-sqlite3) bun add @wxn0brp/db-storage-sqlite GitHub
mongodb MongoDB bun add @wxn0brp/db-storage-mongodb GitHub
bin Single binary file (msgpack) bun add @wxn0brp/db-storage-bin GitHub
dir-c Native C via bun:ffi (Linux) Manual installation (see repo) GitHub
csv CSV files bun add @wxn0brp/db-storage-csv GitHub
web-storage Browser localStorage/sessionStorage/IndexedDB bun add @wxn0brp/db-storage-web GitHub
length Fixed-length binary records bun add github:wxn0brP/ValtheraDB-storage-length#dist GitHub
crypt AES-256-GCM encrypted bun add github:wxn0brP/ValtheraDB-storage-crypt#dist GitHub
rocks RocksDB key-value bun add github:wxn0brP/ValtheraDB-storage-rocks#dist GitHub
accdb MS Access via ODBC bun add github:wxn0brP/ValtheraDB-storage-accdb#dist GitHub
xlsx Excel via xlsx-js bun add github:wxn0brP/ValtheraDB-storage-xlsx#dist GitHub
rn React Native AsyncStorage bun add @wxn0brp/db-storage-rn GitHub
git Git-backed storage (dir) bun add @wxn0brp/db-storage-git GitHub

Creating a Custom Adapter

See the Adapter Tutorial for a step-by-step guide on building your own storage adapter - CRUD variants A/B/C and the specialized Variant D.