Skip to main content

Crate sqlive

Crate sqlive 

Source
Expand description

SQLite connections whose commits rerun the live queries they change.

A Database holds one database’s connections: a writer, readers beside it, and upkeep threads that checkpoint its WAL and keep its planner’s statistics. Each connection is a HostSql, and the host’s Policy judges each statement as SQLite prepares it; NoPolicy adds nothing to sqlive’s own rules. A write transaction captures what it changed, and a live read records the tables, columns and rows its statements read: sqlive parses each statement’s SQL into the conditions that narrow each table it reads. sqlive then judges a commit’s row changes against the reads of each live query whose scopes the changed rows could pass, to tell whether the query’s result could have changed. A Handle holds the subscriptions the judged commits wake, indexed by the values their scopes’ equalities hold, and the failure that ends every later call.

A Database also tells its host the main database file’s size after each checkpoint, its checkpointer’s or the host’s, through a CheckpointedSize (Database::checkpointed_size), so the host can show the file’s size without reading the file itself.

Re-exports§

pub use panic_as_error;
pub use rusqlite;

Modules§

random_scopes
Random live queries and writes over a schema whose joins, views, subqueries and conditions sqlive narrows by, so a test can check that a live query runs again whenever a commit changes what it returns. sqlive’s own test runs them over plain tables, and a host’s test runs them over the host’s own writes. A seed reproduces a case.
sql
SQLite tokens used to inspect CREATE statements without matching comments or strings.
triggered_inserts
A workload of inserts that fire triggers, for measurements of what one triggered write costs.

Structs§

Answers
The answers to the lookups affected has run, keyed by lookup and value or by condition and values. Rows that share a value, and a row’s old and new images that agree on the columns a condition names, share one run of the lookup.
AttemptCommits
Every commit made outside one attempt since it began, kept until the attempt names the rows its wait depends on.
CheckpointedSize
A host’s view of the main database file’s size in bytes after the latest checkpoint (Database::checkpointed_size). Each view keeps its own mark of the sizes it has returned.
CommitScope
The work a commit belongs to: a commit made on a thread running inside enter(scope, ..) belongs to scope.
CommitState
What a subscription has seen of its handle: whether a commit changed what it waits on, and whether the handle closed or failed.
CommitSubscription
One waiter on a handle’s commits: a live query’s, a change watch’s, or the host’s own.
ConnectionWork
The work a connection counts: its commits, its reads of the schema cookie, and the steps of the statements it runs for the app and for live queries’ lookups.
ConnectionWorkCounter
Where connections count their work. Clones count into the same place.
CookieScope
Holds the cookie for one transaction that runs no DDL. Dropping the last scope clears the stored cookie.
Database
One database’s connections and upkeep threads.
DatabaseChanges
A live commit observation. DatabaseChanges merges several commits into one change and ends when the writer closes. Its methods convert the handle’s failure into E and return that.
FunctionCall
One call of a SQL function registered through a connection’s setup.
Handle
The failure state and the subscriptions that several databases share: a failure in one fails every later call and live query on each, with the host’s failure type F.
HandleFailure
What a handle fails with when its host has no failure of its own: the engine’s failure that ended it, shared by every later call.
HostSql
A connection to a database, as its host runs SQL on it: the host’s own statements and the app’s, each judged by the authorizer and the host’s policy P.
Judged
A write’s changes, and how each live query that waited on known reads and that the changes could affect judged them in the write’s transaction, before it committed.
LastRow
Where a run finds the row its scope ends at.
LiveQuery
A subscription’s results and lifetime; dropping it ends future runs. Its results fail with E, the query closure’s own error type.
LiveQueryClosed
The query was dropped before its request could be replaced.
LiveQueryRequests
Shared access to replacing a live query’s request.
LiveQueryRevision
A request revision assigned by one live query.
LiveQueryRuns
How often a live query had run when asked, for tests and benchmarks that measure how many of its runs writes caused, and how many found nothing new.
LocalSql
The host’s local SQL scope; it ends as it drops.
Lookup
A join’s lookup: whether a row of the partner FROM item, in the scope the run gave it, holds a value equal to the changed row’s join column, as the statement’s equality compares them.
NoPolicy
The policy of a host that adds nothing to sqlive’s own rules: it refuses no statement.
Operation
One row operation of the app phase.
Options
How to open a database’s connections. Every connection gets a policy of its own from policy, and the same setup.
PolicyAction
One action SQLite reports, as the authorizer asks the policy about it.
ProfiledStatement
One statement execution the profile saw.
ReadCapture
What a read context’s statements read. Each statement running has its own frame, innermost last, so a statement a row mapper starts records its own reads and leaves the statement around it with its own. The first frame holds reads made outside any statement.
ReadFrame
What one statement read, as SQLite reported it while preparing it.
Reader
One of a database’s readers, reserved for its caller until it drops. Dropping it wakes a caller waiting for a reader, even when a call on it panics.
ReconfigurableLiveQuery
A subscription whose request may be replaced while it runs. Its results fail with E, the query closure’s own error type.
ReconfigurableLiveQueryEvent
One result with the exact request and revision that produced it.
RowChange
One change a commit made to a table’s column or row.
RowCondition
A run’s condition: what it tests of a term, with the run’s parameters.
RowImage
The values of some of a changed row’s columns, as a write recorded them: its key’s, and those a waiting live query reads or its scope tests.
Scopes
What one run of a statement depends on: the scope of each table it read as one of its sources, and the app’s views and the CTEs it read as sources of their own, by the names SQLite reports reads through them by, whose tables’ rows those scopes cover. A table read otherwise, as through a view read whole, depends on every row. Empty when the statement’s shape keeps every table whole.
Setup
What a connection’s setup may register.
SnapshotValue
One value the host keeps in memory, as one connection’s transactions read it: the host’s SQL functions hold it and read it with Self::get.
SqliteSettings
SQLite settings for every connection sqlive opens to a database: the writer and the readers of a writable handle, and every connection of a read-only one. A setting left None keeps SQLite’s own default, except checkpoint_fullfsync on macOS and iOS, which sqlive turns on, and auto_vacuum, which is Incremental. sqlive applies them as each connection opens, before any of its own statements.
SqliteSettingsInEffect
The SQLite settings one connection to a database has in effect, as SQLite reports them. Every connection has the same, except that a writable handle’s writer and statistics connection never checkpoint as they commit.
StatementLog
The statements that reads ran on the connections this log was given to, in order, from when each connection got it. Clones share one log.
StatementReads
What the statements prepared while observing read: each column, in the order first read, and each function they call, ASCII lowercase.
StatementScope
The scopes the statement is prepared in that the policy asks about.
TableRead
What a run read from one table.
UnrecordedTables
Tables whose changes no write records for live queries, lowercase.
WholeViews
The views and tables a live query reads whole: a read through one of them depends on the object itself, which can change with no change to the tables it reads.
WriteSql
The scope the app’s write SQL runs in, from its making until it drops.

Enums§

Affinity
A column’s affinity, as SQLite derives it from the declared type.
AnalysisLimit
How many rows of each index ANALYZE reads.
AutoVacuum
What happens to the pages deleted content frees.
CacheSize
A page cache’s size, which SQLite counts in pages or in kibibytes.
CacheSpill
Whether a transaction may spill changed pages before it commits.
CheckpointMode
SQLite’s checkpoint modes (PRAGMA wal_checkpoint).
CommitPoint
A point a write transaction passes as it commits, for tests that stop or end the process there.
EngineFailure
A failure of sqlive’s own that ends its handle: every later call and live query fails with the host’s failure built from it.
Error
Why a call failed.
IncrementalVacuum
How many free pages an incremental vacuum gives back.
JournalSizeLimit
How large the WAL file may stay after a checkpoint resets it.
Judging
What a write asks of SQLite about a changed row.
LiveQueryCause
Why this run was requested; the first run answers the initial request.
NoAnswer
Why a question about a changed row has no answer.
Owner
Whose statement SQLite is preparing.
PageSize
A database page size: a power of two from 512 bytes to 64 KiB.
Recorded
Whether a statement run through app_query belongs to a read, whose statements a test can record, rather than a write or a migration.
Refresh
How much of the schema the policy reads again.
RowScope
A predicate over a table’s rows. A change reruns a query when its row passes in its old or its new image.
SecureDelete
Whether deleted content is overwritten.
SqlValue
A value SQLite stores.
TempStore
Where temporary tables and indices are kept.
TemporaryDirectoryError
Why the folder for temporary tables could not be named (E1).
WalAutocheckpoint
When sqlive checkpoints the WAL by itself.
WalCheckpoint
What a checkpoint did, as SQLite reports it.

Constants§

CHECKPOINT_PAGES
The WAL size at which sqlive checkpoints where the app leaves it unset: SQLite’s own automatic checkpoint size.
LOOKUP_STEPS
The most SQLite steps one question about a changed row runs. A lookup no index serves reads its partner row by row; past this it stops and the query runs again, so a write’s cost stays bounded whatever the app’s indexes.
ROWS_PER_TABLE
Past this many row changes to one table, a write records only that the table changed, not each row, so its memory stays bounded; every live query that reads the table then runs again.

Traits§

HostError
What the engine’s error asks of the host’s failure and refusal types: errors that cross threads, which the engine finds again inside SQLite’s.
Policy
What the host adds to the authorizer’s rules.
RollbackJoin
A caller’s error for a transaction it runs: built from sqlive’s errors, and able to keep a failed rollback beside its own cause.

Functions§

affected
Whether changes could change what reads returned. Past ROWS_PER_TABLE row changes to one table, a join’s values in that table count as matched without a lookup, as a table changed whole would, so a write’s lookups stay bounded. A question that runs past LOOKUP_STEPS and stops leaves sqlive unable to tell, so reads count as changed whatever the other questions answer (§4).
committing
The scope of the call committing on this thread.
enter
Run run with commits made on this thread attributed to scope, if any.
report_cost
One measured number, as a line scripts/perf.sh reads: COST metric=<name> value=<n> unit=<ms|ratio|count>. Lower is better in every unit. A character in metric outside letters, digits and _./- becomes _, so a caller can pass a label unchanged.
report_time
report_cost for a time, in milliseconds.
set_temporary_directory
Keep SQLite’s temporary tables in directory, for every database this process opens from now on. Call it before opening any database.

Type Aliases§

ColumnSet
The table and column names a run read, as pairs.
Lookups
Runs one question about a changed row: whether SQLite found a row.
PolicyError
The error a connection judged by P returns.
ReadSet
The tables a run read, with the rows and columns of each.
Run
One run of the query for a request: it reads on a connection it releases before returning, and hands its reads to the subscription.