Expand description
SQLite persistence for the observable model (docs/persistence.md).
An app depends on this crate directly, beside the day facade with its model feature on,
and starts a model module with use day_persistence::prelude::*. The crate is built on the
framework’s public API and nothing in the framework depends on it; #[derive(Model)] comes
from day-persistence-macros and the web engine from day-sqlite-worker.
The engine owns the data; memory holds a working set. A ModelContainer opens a
database through a pluggable SqliteDriver, creates or migrates each model’s table,
and stops: no rows are read at open, so opening a million-row store costs the same as
opening an empty one. Rows enter memory by faulting: a typed ModelContainer::get, a
batch ModelContainer::ensure_resident, or a list binding materializing the rows it is
about to show. Each model’s Store is that working set (an ordinary day-model store,
so every binding and accessor works on it unchanged), bounded by a per-table cache limit;
clean rows nothing observes leave silently and fault back on the next read.
The write half is day-model’s change log, folded. Any write requires its row resident
(editing is what faulted it in); at the end of any turn that touched a store (autosave,
the default) the accumulated changes fold into the smallest statement list that expresses
them: twenty keystrokes into one field is one UPDATE; a row inserted and then filled is
one INSERT; a thousand-child cascade is a handful of chunked DELETEs.
Typed live queries (ModelContainer::query) compile entirely to SQL: predicate to
WHERE (relation crossings as correlated EXISTS, full-text as an FTS5 subquery, spatial
boxes through the R*Tree shadow), sort to ORDER BY with the key as tie-break, window to
LIMIT, so the engine’s indexes answer them at any table size. Live maintenance is
dependency-gated: a change to a column no query mentions costs nothing; a change a query
does depend on marks it stale, and one requery after the turn’s flush re-derives its id
set, diffed against the previous answer so a list animates the difference instead of
reloading. Rows behind the ids stay lazy: the query holds ids, and the list faults the
window it shows.
The driver is a trait so the engine is the app’s choice: the built-in Sqlite driver
(feature driver-rusqlite, on by default) compiles a bundled SQLite, links the system one
(system), or builds SQLCipher (cipher); the Recorder answers from fixtures and
records every statement, which is what keeps persistence assertable headlessly: a test
can check the SQL a UI action produced without a database on disk.
Another connection’s committed writes arrive through ModelContainer::check_external,
which re-reads only the resident rows and re-runs the live queries: O(working set), never
O(table). Row identity is the model’s #[model(id)] key; display order is a projection
concern and is not persisted.
Modules§
- prelude
- What a model module starts from:
use day_persistence::prelude::*;beside the app’suse day::prelude::*;. The container, theModeltrait and its derive, the relation markers, the drivers andschema!.
Macros§
- schema
schema![Trip, Lodging]: the models a container manages.
Structs§
- Capabilities
- What a driver can and cannot do, so the container degrades visibly instead of silently.
- Col
- A typed column reference, what
Trip::name()returns (the derive emits one inherent fn per persisted field). It knows the column’s name and its stored encoding, so a predicate built from it compares in the column’s stored language whatever codec the field uses. - Column
Def - One column of a model’s table, as the derive declares it.
fieldis the struct field the column stores: the change log speaks field names, the SQL speaks column names, and this is where the two meet (they differ only under#[model(column = "…")]). - Count
Query - A live count over one model’s table, the badge query:
SELECT COUNT(*)behind the same dependency-gated staleness asQuery, holding no id vector, so a count over a million-row result costs O(1) memory. Clone shares the same state. - Database
Worker - An explicitly asynchronous database queue. Construct the container in
open’s factory: its connection, caches, model handles and query observers stay on this worker until close. Only ownedSendarguments and results cross threads. Clones share FIFO admission order. Do not return modelStore/Elemhandles or signals: their cross-thread facilities do not make them independent of this queue’s connection and lifetime. Return model values/IDs. - DbError
- Why a persistence operation failed.
messageis for the log;kindis for the code path that can do something about it. - Deps
- What a fetch reads, and therefore what can move a row through it.
- Fetch
- A declared fetch: predicate, sort, window.
- FtsRef
- What
Trip::fts()returns when the model declares#[model(fts(…))]. - GeoRect
- A bounding box for
GeoRef::within. - GeoRef
- What
Trip::geo()returns when the model declares#[model(spatial(…))]. - Json
- The serde codec: any
Serialize + Deserializetype as aTEXTcolumn SQLite’s ownjson_*functions can reach.#[model(json)]is sugar for#[model(with = Json)]. - LinkDef
- One
#[model(link(…))]as the derive emits it:owner.local = target.remoteis the join. - Linked
- The marker a
#[model(link(…))]field carries. It has neither a column nor state; the type is what names the far model for the derive. - Many
- The to-many side: a marker field. It stores nothing; membership lives in the children’s
foreign keys (or the join table), and the field exists so the relation has an observable
path of its own and a declared home for
#[model(relation(…))]. Reads go through the generated accessor’sRelationRef. - Migration
Plan - Staged migrations: anything with intent behind it (a rename, a split) gets a stage the app writes; each stage runs in its own transaction against the raw connection, and versions only go up. Lightweight migration (added/dropped columns and indexes) runs afterward, inferred from the schema fingerprint.
- Model
Container - An open database and the working-set caches over it. Clone is shallow: clones share the connection and the dirty state.
- One
- A to-one reference: the foreign-key column on the child row.
One<M>alone is a required reference (NOT NULL); wrap itOption<One<M>>for a nullable one.Copy, 16 bytes, and an ordinaryColumnValue, so the derive treats the field as a plain column whose stored form is the target’s key shape. - Open
Options - How to open the database. Built by the driver’s own constructors (
Sqlite::atetc.); public so alternative drivers speak the same vocabulary. - Query
- A live, typed result set over one model’s table: ids only, answered by the engine and
kept current by dependency-gated requeries. Rows stay lazy: fault the ones you show
(
Query::materialize, or a list source doing it for you). Clone shares the same set. - Query
Builder - Builder for a
Query:container.query::<Trip>().filter(…).sort(…).live(). - Query
Conn - Recorder
- A driver that answers from fixtures and records every statement: the piece that keeps
persistence assertable with no database on disk.
let (driver, log) = Recorder::new(); - Recorder
Conn - Recorder
Log - The recorded statement log, shared with the test that holds it.
- Registrar
- What
Model::wirereceives: the container mid-open. Wiring failures collect here and fail the open with the first one, named. - Related
Dep - One relation’s contribution to a fetch’s dependencies.
- Relation
Col - A relation, as a predicate builder: what
Trip::lodging()returns. The instance accessor of the same name (trip.lodging()) reads and writes the relation; this one asks questions about it in a query. They cannot collide: one takesself, this one does not. - Relation
Def - One declared relation, as the derive records it on the parent (
Many) side. - Relation
Ref - What the generated accessor for a
Manyfield returns: the relation, addressed from one parent. Reads are tracked through the parent’s field path (membership changes wake exactly the readers of this parent’s relation), and writes go through the children’s foreign keys, where membership is stored. - Result
Set - A query’s result set: the ids the SQL last answered, and the diff machinery that turns the next answer into list deltas.
- Schema
- The set of models a container manages; build with
schema!. - Secret
- A key for an encrypted database. Redacted in Debug and zeroed on drop; where it lives between launches is the app’s business, never this crate’s.
- Sort
- Spatial
Cols - The column pair a
#[model(spatial(lat = …, lon = …))]declaration names. - Sqlite
- Worker
Options - Worker
Request - An eagerly submitted operation. Dropping a read cancels it if it has not started. Dropping a write’s result never cancels an accepted transaction: await it to learn commit success.
- Worker
Snapshot - A committed value and the worker-local transaction revision it represents.
- Worker
Subscription - A bounded, latest-value subscription. Slow consumers receive the newest committed result, not an unbounded queue of intermediate refreshes. Drop to unsubscribe. Values are compared on the worker, so unchanged results do not wake the UI. This is not a transaction event log.
Enums§
- DbError
Kind - Delete
Rule - What deleting a referenced parent does. Declared per relation
(
#[model(relation(delete = "…"))]); the default isNullify(also SwiftData’s default for@Relationship). - Delta
- What a change did to the result set.
- Location
- Where the database lives.
- Pred
- A predicate as a value. Compiles to SQL; the fallback evaluator (
Pred::eval) exists for drivers that cannot fold case exactly, and for tests. - Quant
- How many related rows have to satisfy the inner predicate.
- Query
Events - What a query’s consumers have not yet seen.
Deltascan animate a list row by row;Reloadmeans the whole set moved (a fetch swap, a tangled requery) and a reload is the accurate answer. - SetChange
- What adopting a fresh answer did to a result set.
- SqlType
- A column’s declared type. Part of the schema fingerprint, so changing one is a migration.
- Value
- SQLite’s five storage classes, and nothing else; no driver type reaches the layer above.
Constants§
- DEFAULT_
CACHE_ LIMIT - The default per-table bound on resident rows (
ModelContainer::set_cache_limit).
Traits§
- Column
Value - A Rust type that knows how to be a column. One impl per type: its canonical form.
- Model
- A persistable model: an
Identifiedobservable struct with a schema half. Implemented by#[derive(Model)]; the container consumes it. - Row
- One result row, by position.
- RowView
- A row, as a predicate can read it: column name → stored value. Implementations answer in the column’s stored language (through the field’s codec), which is the language predicates encode their arguments into, so comparisons never mix representations.
- Sqlite
Connection - One open connection. Everything above speaks plain SQL and
Values through it. - Sqlite
Driver - The engine trait. Object-safe on the connection side, so the container stores
Box<dyn SqliteConnection>and never names an engine type. - Value
Codec - A named alternative representation for
T, serde’s#[serde(with = …)]idiom. Implement on a unit struct; select it per field with#[model(with = …)].
Functions§
- compare_
values - SQLite’s cross-class ordering (NULL < numbers < text < blob), with one difference:
Realcompares bytotal_cmp, so a NaN that reaches the fallback evaluator still orders deterministically instead of poisoning it. - encode_
column - The encoder a plain (codec-less) field’s
Colcarries. - model_
fingerprint - The declared schema’s fingerprint: table, columns, types, flags, indexes. Equal fingerprints open instantly; a difference migrates or refuses, never silently.
- rank
- Order by FTS relevance (bm25, best first); pair with a
matchespredicate. - wire_
join - Wire one many-to-many; called from the derive-generated
Model::wire. - wire_
to_ many - Wire one
Manydeclaration; called from the derive-generatedModel::wire.
Derive Macros§
- Model
- The derive for the
Modeltrait (the two share a name, souse day_persistence::Modelbrings both): everything#[derive(Observable)]generates plus the schema half.#[model(id)]marks the key; docs/persistence.md lists the field and struct options. A persistable model: everything#[derive(Observable)]generates, plusimpl day_persistence::Model: table name, column list, row↔struct mappers and the default row. See day-persistence’s crate docs anddocs/persistence.md.