Skip to content

Quickstart

Audience: beginners — first model stored in about five minutes.

This guide walks through install, open a database, define a schema, and read a row back. It mirrors the project README examples so you can trust the same mental model everywhere.

Evaluating ModelVault?

Read Why ModelVault for positioning and the comparison matrix vs SQLite, JSON, and TinyDB.

Already use embedded databases?

ModelVault is schema-first: types and constraints are declared before writes; the engine rejects invalid data at the boundary. See Core concepts for the full model.

Install

Requires CPython 3.9+. Wheels use the stable ABI (cp39-abi3).

pip install "modelvault>=0.16.0,<0.17"

Add to your application Cargo.toml:

[dependencies]
modelvault = "0.16"

Python: models, insert, get (recommended)

The recommended path is a dataclass or Pydantic model plus modelvault.models.collection—your class is the schema.

# Setup: class-defined schema + in-memory DB.
from __future__ import annotations

from dataclasses import dataclass
from typing import Annotated, Optional

import modelvault


@dataclass
class Book:
    __modelvault_primary_key__ = "title"
    __modelvault_indexes__ = [
        modelvault.models.index("year"),
        modelvault.models.unique("title"),
    ]

    title: str
    year: Annotated[int, modelvault.models.constrained(min_i64=0)]
    rating: Optional[float] = None


db = modelvault.Database.open_in_memory()
books = modelvault.models.collection(db, Book)

books.insert(Book(title="Hello", year=2020, rating=4.5))
print("get:", books.get("Hello"))
print("modelvault", modelvault.__version__)

Run it (from this repo)

make python-develop
.venv/bin/python your_script.py   # paste the snippet above

Output:

get: Book(title='Hello', year=2020, rating=4.5)
modelvault 0.16.0

For a durable file, use Database.open("app.modelvault") instead of open_in_memory(). Pydantic follows the same pattern—see the Pydantic guide.

Rust: open and register a collection

Use the modelvault facade crate. This example is in-memory; for on-disk storage, use Database::open("my.modelvault")?.

use std::borrow::Cow;

use modelvault::prelude::*;
use modelvault::schema::FieldPath;
use modelvault::FieldDef;
use modelvault::Type;

fn main() -> Result<(), DbError> {
    let mut db = Database::open_in_memory()?;
    println!("opened: {}", db.path().display());

    let (id, ver) = db.register_collection(
        "books",
        vec![FieldDef {
            path: FieldPath::new([Cow::Borrowed("title")])?,
            ty: Type::String,
            constraints: vec![],
        }],
        "title",
    )?;
    println!("registered collection id={} version={}", id.0, ver.0);
    Ok(())
}

Run it (from this repo)

cargo run -q -p modelvault --example open

Output:

opened: :memory:
registered collection id=1 version=1

What the current release includes

Capability Notes
Schema catalog Versioned collections, fields, constraints, indexes
Validation on write Types and engine constraints before append
Queries Equality, ranges, AND/OR, order_by, limit
Durability Transactions, checkpoints, compaction, recovery modes
Nested paths Multi-segment fields (e.g. profile.timezone) end-to-end
DB-API (read-only) Experimental modelvault.dbapi with a minimal SELECT subset

SQL and SQLAlchemy

ModelVault is model-first. Full ISO SQL and SQLAlchemy are planned post–current milestone. See the roadmap on GitHub.

Reference material

Next steps

Topic Guide
Why ModelVault exists Why ModelVault
Pydantic & FastAPI Pydantic · FastAPI (AsyncDatabase, async routes)
Mental model Core concepts
Python in depth Python guide
Class schemas & projections Models & collections
Disk vs memory Storage modes
Compare alternatives Comparisons
Engine design Specifications

Contributors

From the repo root:

python3 -m venv .venv
.venv/bin/python -m pip install -U pip
make check-full

This runs Rust and Python checks, tests, and verify-doc-examples (stdout from snippets on this page, the root README, and selected guides must match documented output).