Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RiffDB Handbook

RiffDB is a standalone, contract-first operational database. Applications declare entities, commands, invariants, outcomes, queries, and least-authority roles. They mutate state only by invoking compiled commands; RiffDB owns the concurrency checks, idempotency record, durable outcome, provenance, events, and projection progress.

RiffDB is currently a proof of concept supporting single-node operation and single-primary asynchronous follower replication. It is suitable for evaluation and local agent-built applications, not production workloads. Read Known Limitations, Compatibility, and Security before choosing an environment.

Choose a path

GoalStart here
Understand the modelWhat RiffDB Is
Install a user serviceInstallation
Build and run an applicationYour First Application
Give an agent typed database toolsMCP Agent Cookbook
Compare the safety model with PostgreSQLPostgreSQL Safety Comparison
Operate multiple local databasesMultiple Databases
Look up a commandCLI Reference

The application boundary

contract + RiffQL + symbolic roles
                 |
                 v
       checked application lock
                 |
       +------+-------+---------+---------+
       |      |       |         |         |
     Rust    Go   TypeScript  Python     MCP
       |      |       |         |         |
       +------+-------+---------+---------+
                 |
       shared application service
                 |
 deterministic runtime + commit coordinator
                 |
          authoritative storage

The transports do not define separate semantics. CLI, generated clients, gRPC, and MCP all enter the same application service and authorization boundary. MCP never opens storage directly.

First successful loop

From a source checkout:

cargo run -p riffdb-cli -- new item-desk
cd item-desk
../target/debug/riffdb dev --seed --run

The scaffold contains the contract, a bounded query, seed commands, exact lock, and generated clients. Continue with Your First Application for the review boundaries and installed workflow.

What the database proves

  • Business invariants are evaluated by the database under concurrency.
  • A retry keeps one idempotency identity and recovers the committed outcome.
  • A commit atomically records mutations, outcome, events, provenance, and its commit-log entry.
  • Queries execute against one authoritative snapshot with compiler-proven bounds.
  • Projections expose frontiers so callers can request read-after-commit consistency explicitly.
  • Credentials expose named operations and scopes, not ambient storage access.