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§
- Blob
- A lazy
BLOBcolumn.Defaultis the stored, unread state;Blob::newcarries bytes to the next flush. The bytes are read through the field’s accessor (BlobField::bytesand friends), never through the value itself. - Blob
Reader - A
std::io::Readover a lazy blob, in 256 KiB chunks. - Capabilities
- What a driver can and cannot do, so the container degrades visibly instead of silently.
- Checkpoint
- What
PRAGMA wal_checkpoint(TRUNCATE)answered (ModelContainer::checkpoint): the three columns of its status row. The engine reads the counts after the checkpoint, so a completed one answers0and0(the log was emptied); a busy one describes the log it had to leave behind. Both counts are-1when the database is not in WAL mode (a memory database, orwal: false). - 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.
- Foreign
KeyViolation - One row of
PRAGMA foreign_key_check(ModelContainer::foreign_key_check): a child row whose reference names no parent. - 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.
- RowChange
- One row of a transaction’s folded change set, as
TransactionParticipant::before_commitreceives it: every row the ORM’s pipeline wrote in the transaction (model edits, relation upkeep, in-process cascades), one entry per (table, key). Rows the engine’s ownON DELETEclause removed without the process faulting them are not in the set. - 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. - Refresh
- The cache refresh a participant asks for after its own SQL may have changed model rows that were already flushed from the caches.
- RowChange
Kind - What happened to a
RowChange’s row over the transaction. Same-row changes coalesce the way the autosave fold does: an insert absorbs later updates, a delete absorbs everything before it, updates union their columns, and a wholesale write supersedes a column list. - 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.
- Write
Origin - Why a durable transaction is being performed. Cache refreshes use EXTERNAL_AUTHOR and do not constitute a write transaction. Remote imports persist but must not echo outbound.
Constants§
- DEFAULT_
BLOB_ CACHE_ LIMIT - How many bytes of lazy
Blobvalues a container keeps in memory by default (32 MiB): the memo behindBlobField::bytes, bounded in bytes rather than rows. - DEFAULT_
CACHE_ LIMIT - The default per-table bound on resident rows (
ModelContainer::set_cache_limit).
Traits§
- Blob
Field - What a
Blobfield’s accessor offers beyond the plain field: the bytes, on demand. - 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. - Transaction
Participant - Queue-confined extension participating in the SAME SQL transaction as model changes.
Callbacks must use only the supplied connection, never re-enter the container, commit,
roll back, perform network I/O, or mutate reactive models. Returning an error aborts the
transaction.
before_commitruns after worker reactions and intermediate saves settle. Persist extension state transactionally; callbacks may run again following a rollback. - 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. - ident
nameas a SQL identifier: double-quoted, an embedded"doubled. Quoted, any name reaches the engine as itself: a keyword (order,group), a space, a quote, an emoji. Every statement the container writes names its tables and columns this way, and raw SQL written against them should too.- 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.