Your First Application

This page documents the self-contained application scaffold. To add RiffDB to an existing project with riffdb.toml, an empty schema, database-shaped verbs, and selected SDK targets, use the Database-Shaped Project Workflow.

This walkthrough creates the small generated Item application, runs it on a disposable RiffDB database, and shows where source intent becomes an exact reviewed application.

Prerequisites

Install the binaries with the source checkout convenience installer, or build the workspace once:

cargo build --locked -p riffdb-cli -p riffdb-server

Scaffold

From the directory that should contain the new project:

riffdb new item-desk
cd item-desk

The generated repository separates three things:

Inspect the contract before accepting a changed lock. The starter command creates an item through a declared command; no generated client contains a raw entity mutation.

Check, lock, and generate

riffdb application check
riffdb application lock --write
riffdb application lock --check
riffdb application generate --locked

check is read-only. lock --write is the explicit point at which new compiler-owned identities are accepted. generate --locked reproduces clients only for the exact lock. Deployment performs all local source, role, query, and generated-artifact preflight before its first remote mutation.

Run a disposable server

riffdb dev --seed --run

The command starts an isolated loopback server, bootstraps through the normal capability path, deploys the exact application, binds the requested role, runs seed JSONL as ordinary idempotent commands, and starts the generated example. It removes the disposable database and credentials when the process exits.

Use this mode while authoring. For a persistent user service, follow Installation and deploy against the configured database alias.

Make a change

Add a field, command, or bounded query using the Contract Authoring Reference and RiffQL Language. Then repeat the check and lock sequence. A compatible successor must increment the contract version and preserves the exact active parent identity.

Schema evolution supports the documented additive subset and reviewed .riffm contract migrations (see Contract Migrations). If disposable local development data needs a destructive reset, pass riffdb dev --reset or use the explicit offline reset procedure in Upgrade, Reset, and Removal; never delete an active database behind a running server.

Choose a client

• Rust uses the stable Rust application facade and generated operation module.
• Go uses generated facades over the retained Rust driver host.
• TypeScript uses the checked generated package.
• Python uses the Rust-backed sync or async driver.
• MCP exposes only tools authorized for the bound role and selected database.

All five preserve the same operation identities, values, closed outcomes, idempotency behavior, and public errors.