Skip to main content

Crate day_persistence

Crate day_persistence 

Source
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’s use day::prelude::*;. The container, the Model trait and its derive, the relation markers, the drivers and schema!.

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.
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 answers 0 and 0 (the log was emptied); a busy one describes the log it had to leave behind. Both counts are -1 when the database is not in WAL mode (a memory database, or wal: 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.
ColumnDef
One column of a model’s table, as the derive declares it. field is 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 = "…")]).
CountQuery
A live count over one model’s table, the badge query: SELECT COUNT(*) behind the same dependency-gated staleness as Query, holding no id vector, so a count over a million-row result costs O(1) memory. Clone shares the same state.
DatabaseWorker
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 owned Send arguments and results cross threads. Clones share FIFO admission order. Do not return model Store/Elem handles 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. message is for the log; kind is 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.
ForeignKeyViolation
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 + Deserialize type as a TEXT column SQLite’s own json_* functions can reach. #[model(json)] is sugar for #[model(with = Json)].
LinkDef
One #[model(link(…))] as the derive emits it: owner.local = target.remote is 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’s RelationRef.
MigrationPlan
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.
ModelContainer
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 it Option<One<M>> for a nullable one. Copy, 16 bytes, and an ordinary ColumnValue, so the derive treats the field as a plain column whose stored form is the target’s key shape.
OpenOptions
How to open the database. Built by the driver’s own constructors (Sqlite::at etc.); 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.
QueryBuilder
Builder for a Query: container.query::<Trip>().filter(…).sort(…).live().
QueryConn
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();
RecorderConn
RecorderLog
The recorded statement log, shared with the test that holds it.
Registrar
What Model::wire receives: the container mid-open. Wiring failures collect here and fail the open with the first one, named.
RelatedDep
One relation’s contribution to a fetch’s dependencies.
RelationCol
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 takes self, this one does not.
RelationDef
One declared relation, as the derive records it on the parent (Many) side.
RelationRef
What the generated accessor for a Many field 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.
ResultSet
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_commit receives 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 own ON DELETE clause 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
SpatialCols
The column pair a #[model(spatial(lat = …, lon = …))] declaration names.
Sqlite
WorkerOptions
WorkerRequest
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.
WorkerSnapshot
A committed value and the worker-local transaction revision it represents.
WorkerSubscription
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§

DbErrorKind
DeleteRule
What deleting a referenced parent does. Declared per relation (#[model(relation(delete = "…"))]); the default is Nullify (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.
QueryEvents
What a query’s consumers have not yet seen. Deltas can animate a list row by row; Reload means 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.
RowChangeKind
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.
WriteOrigin
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_CACHE_LIMIT
The default per-table bound on resident rows (ModelContainer::set_cache_limit).

Traits§

ColumnValue
A Rust type that knows how to be a column. One impl per type: its canonical form.
Model
A persistable model: an Identified observable 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.
SqliteConnection
One open connection. Everything above speaks plain SQL and Values through it.
SqliteDriver
The engine trait. Object-safe on the connection side, so the container stores Box<dyn SqliteConnection> and never names an engine type.
TransactionParticipant
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_commit runs after worker reactions and intermediate saves settle. Persist extension state transactionally; callbacks may run again following a rollback.
ValueCodec
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: Real compares by total_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 Col carries.
ident
name as 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 matches predicate.
wire_join
Wire one many-to-many; called from the derive-generated Model::wire.
wire_to_many
Wire one Many declaration; called from the derive-generated Model::wire.

Derive Macros§

Model
The derive for the Model trait (the two share a name, so use day_persistence::Model brings 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, plus impl day_persistence::Model: table name, column list, row↔struct mappers and the default row. See day-persistence’s crate docs and docs/persistence.md.