ModelVault

The database for application models.

ModelVault is a schema-first, typed embedded database for application data. Store Pydantic models, dataclasses, or Rust structs directly—validation, indexes, migrations, and durability are built in. Ship a single .modelvault file with your app, or open :memory: in tests. One engine powers both Python and Rust.

What ModelVault is not

ModelVault does not aim to replace PostgreSQL, compete with SQLite as a general SQL database, or support SQLAlchemy as a primary interface today. It is model-first: typed APIs in Rust and Python, plus an experimental read-only SQL subset for DB-API interop. See Non-goals below.

• Why ModelVault?

  ---

  When embedded SQL, JSON files, or TinyDB leave gaps for application data.

  Why ModelVault

• Quickstart

  ---

  Install, define a model, insert your first row—in about five minutes.

  Quickstart

• Pydantic & FastAPI

  ---

  Your API types and your storage schema stay aligned. FastAPI apps use AsyncDatabase and async def handlers.

  Pydantic · FastAPI

• Comparisons

  ---

  ModelVault vs SQLite, JSON, TinyDB, and DuckDB—with clear boundaries.

  Comparisons

Why ModelVault?

Most apps need local, durable storage for domain objects—users, settings, inventory lines, project metadata—without running a database server. Common choices each impose a tax:

Alternative	Limitation	ModelVault
Relational DBs (SQLite + ORM)	App models must be mapped into tables and SQL migrations; impedance mismatch with Pydantic/dataclasses	Model-first schemas; validation on write; nested objects as first-class typed paths
JSON / YAML files	No indexes, weak queries, integrity and evolution are manual	Typed storage, indexes, queries, and a crash-safe append-only file format
TinyDB	Lightweight documents without production-grade validation or schema evolution	Strict schemas, migrations, indexes, and operational tooling
DuckDB	Built for analytics (OLAP), not everyday app CRUD	Embedded OLTP for application models—complementary, not competing

Full positioning · Comparison matrix

What you get

Benefit	What it means for your app
Store models directly	Your Python class or Rust struct is the schema—no parallel DDL to maintain
Validate on write	Invalid types and constraint violations fail before data reaches disk
Query with indexes	Equality, ranges, AND/OR, order_by, and limit—without standing up a server
Evolve safely	Versioned schema catalog, compatibility checks, and migration helpers (plan / apply)
Deploy as one file	Copy app.modelvault with your binary, installer, or repo—no daemon to operate
Concurrent reads	Many get / query operations can overlap on one Database or AsyncDatabase handle; writes stay exclusive (async policy)

60-second example (Python)

Store a Pydantic model—no hand-written schema JSON:

from pydantic import BaseModel
import modelvault


class Book(BaseModel):
    __modelvault_primary_key__ = "title"

    title: str
    year: int


db = modelvault.Database.open_in_memory()
books = modelvault.models.collection(db, Book)
books.insert(Book(title="Hello", year=2020))
print(books.get("Hello"))

Full quickstart (dataclasses, on-disk files, and Rust)

Who is it for?

Persona	What you get
FastAPI developer	AsyncDatabase + Pydantic models in lifespan; async def CRUD without PostgreSQL for prototypes and small services
Desktop app	Ship a .modelvault file; validation and indexes built in
CLI tool	Durable, typed local data—better than ad-hoc JSON
Local-first app	Offline storage with schema evolution—no database server

Non-goals

ModelVault optimizes for typed application documents in one process, not every datastore use case:

• Not SQL-first — model APIs are primary; full ISO SQL and SQLAlchemy integration are on the roadmap.
• Not a network database — embedded single-writer per file (advisory locks across processes); multiple readers per handle or read_only opens; no replication or server mode in the current release.
• Not OLAP at scale — use DuckDB (or export) for heavy analytics; ModelVault is OLTP-oriented for app state.

Install

PythonRust

pip install "modelvault>=0.16.0,<0.17"

[dependencies]
modelvault = "0.16"

Capabilities (current release)

Area	Summary
Schema-first	Collections with typed fields, constraints, and multi-segment nested paths
Validation on write	Engine rejects invalid data before append
Indexes & queries	Secondary indexes; equality, ranges, AND/OR, order_by, limit
Durability	Transactions, checkpoints, compaction, configurable recovery
Python ergonomics	modelvault.models (recommended) + optional read-only modelvault.dbapi
Operations	modelvault CLI—inspect, verify, backup, checkpoint, compact

Package version 0.16.x on PyPI and crates.io builds on the 1.0 product milestone (0.14.x rebrand) (see Compatibility → Versioning).

Documentation by goal

I want to…	Start here
Understand why ModelVault exists	Why ModelVault · Launch essay
Store my first model in five minutes	Quickstart
Use Pydantic or FastAPI	Pydantic · FastAPI
Learn the mental model	Core concepts
Run sample apps	Examples
Build with Python or Rust	Python guide · Rust API
Run backups and recovery	Operations runbook
Evaluate production contracts	Compatibility · Security

Choose your path

Not sure where to click next? See Choose your path—organized by evaluator, builder, operator, and contributor.