BoxDB

A database for your $5 VPS.

An experimental SQLite client for Rust, TypeScript, Go and the command line. BoxDB adds logical types and validation to ordinary SQLite databases, with an optional readable YAML format for storing data in Git. Version 0 does not preserve old BoxDB file or API compatibility.

Get started

Install the CLI with Node.js 22.18+ on macOS ARM64 or Linux x64 with glibc 2.35+ (Ubuntu 22.04+):

npm install -g @boxdb/cli
boxdb data.db -e "
  CREATE TABLE accounts (
    id INT64 PRIMARY KEY,
    name TEXT NOT NULL,
    balance DECIMAL(12,2)
  );
  INSERT INTO accounts(name,balance) VALUES('Ada','12.50');
  SELECT * FROM accounts;
"

Run boxdb data.db for the interactive shell; .help lists shell commands. Use boxdb --help for CLI options, including JSON output and format conversion. See the CLI README for installation and usage.

To build from this checkout, use cargo install --path . --locked with a current Rust toolchain, native build tools and libclang (Xcode Command Line Tools on macOS; libclang-dev on Debian/Ubuntu).

Migrations and schema export

boxdb migrate new create_accounts
# Edit the generated SQL file, then:
boxdb migrate up data.db
boxdb migrate status data.db --check
boxdb migrate down data.db
boxdb schema dump data.db > schema.sql
boxdb schema dump data.db --format=yaml > schema.yaml

Migrations run through BoxDB and preserve extended types. Each version commits atomically; applied files are checked for changes. Schema dumps include type and migration metadata without application rows. SQL is the default export format; YAML exports a logical schema with nullable columns marked as name?; it is separate from readable database storage. See migration and restoration usage.

SQL and types

SQLite executes queries directly. Tables created through BoxDB are STRICT by default; extended types include bounded integers, string enums, exact decimals, UUID, JSON, UTC instants, calendar dates/datetimes, times of day, intervals and typed arrays. DECIMAL, UUID, INSTANT, DATE, TIME, DATETIME and INTERVAL are native engine values with typed comparison and indexing. JSON is validated opaque text; JSON/JSONB SQL functions and operators are disabled. Table column names cannot end in ?, which marks nullable columns in YAML schema exports. Bind decimal strings for exact input. See native decimals. See temporal arithmetic, type declarations and the storage and validation contract.

FTS5, R*Tree, exact decimal SQL functions, Unicode text functions, regular expressions and vector search are built in for every client. No shared-library loading is needed. See extension examples and storage limits.

Binary files use SQLite's standard page and record format. Native type queries and indexes require BoxDB's patched engine. External writers can bypass BoxDB's additional validation for other extended types. Readable YAML storage executes in memory and publishes a complete snapshot on commit, with one writer per file. See storage formats and Litestream replication.

Use boxdb check data.db --full to diagnose an existing file. Explicit repair and recover commands write to new destinations; see diagnostics and recovery for their limits and client APIs.

Language clients

Install the experimental Rust library from crates.io:

cargo add boxdb

The library source includes a minimal example; cargo doc --no-deps --open opens the API reference. The crate bundles BoxDB's SQLite engine and extensions; building requires native build tools and libclang. A local path dependency also works without Cargo patches.

The TypeScript client runs in Node.js and Bun with a nonblocking API. Follow its build and installation instructions, or install it with npm install @boxdb/client. Separate adapters have their own guides:

Drizzle: queries, transactions, migrations and extended column types.
Better Auth: authentication storage and initial schema generation.
db0: connector setup and transaction handles.

The Go client implements database/sql, with context cancellation, prepared statements and transactions. It uses the Rust core through cgo; follow its native build and local module installation instructions.

For AI agents, the BoxDB skill routes usage tasks to the appropriate client guide and explains BoxDB-specific constraints.

Development

With Rust, libclang, Go 1.23+, a C compiler, Node.js 22.18+, Bun, Just and Python 3.11+ installed, run:

just check