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
affectedhas 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. - Attempt
Commits - Every commit made outside one attempt since it began, kept until the attempt names the rows its wait depends on.
- Checkpointed
Size - 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. - Commit
Scope - The work a commit belongs to: a commit made on a thread running inside
enter(scope, ..)belongs toscope. - Commit
State - What a subscription has seen of its handle: whether a commit changed what it waits on, and whether the handle closed or failed.
- Commit
Subscription - One waiter on a handle’s commits: a live query’s, a change watch’s, or the host’s own.
- Connection
Work - 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.
- Connection
Work Counter - Where connections count their work. Clones count into the same place.
- Cookie
Scope - 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.
- Database
Changes - A live commit observation.
DatabaseChangesmerges several commits into one change and ends when the writer closes. Its methods convert the handle’s failure intoEand return that. - Function
Call - 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. - Handle
Failure - 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.
- Live
Query - A subscription’s results and lifetime; dropping it ends future runs. Its
results fail with
E, the query closure’s own error type. - Live
Query Closed - The query was dropped before its request could be replaced.
- Live
Query Requests - Shared access to replacing a live query’s request.
- Live
Query Revision - A request revision assigned by one live query.
- Live
Query Runs - 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.
- Local
Sql - 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 samesetup. - Policy
Action - One action SQLite reports, as the authorizer asks the policy about it.
- Profiled
Statement - One statement execution the profile saw.
- Read
Capture - 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.
- Read
Frame - 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.
- Reconfigurable
Live Query - A subscription whose request may be replaced while it runs. Its results
fail with
E, the query closure’s own error type. - Reconfigurable
Live Query Event - 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.
- Snapshot
Value - 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. - Sqlite
Settings - 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
Nonekeeps SQLite’s own default, exceptcheckpoint_fullfsyncon macOS and iOS, which sqlive turns on, andauto_vacuum, which isIncremental. sqlive applies them as each connection opens, before any of its own statements. - Sqlite
Settings InEffect - 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.
- Statement
Log - 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.
- Statement
Reads - What the statements prepared while observing read: each column, in the order first read, and each function they call, ASCII lowercase.
- Statement
Scope - The scopes the statement is prepared in that the policy asks about.
- Table
Read - What a run read from one table.
- Unrecorded
Tables - Tables whose changes no write records for live queries, lowercase.
- Whole
Views - 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.
- Write
Sql - 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.
- Analysis
Limit - How many rows of each index
ANALYZEreads. - Auto
Vacuum - What happens to the pages deleted content frees.
- Cache
Size - A page cache’s size, which SQLite counts in pages or in kibibytes.
- Cache
Spill - Whether a transaction may spill changed pages before it commits.
- Checkpoint
Mode - SQLite’s checkpoint modes (
PRAGMA wal_checkpoint). - Commit
Point - A point a write transaction passes as it commits, for tests that stop or end the process there.
- Engine
Failure - 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.
- Incremental
Vacuum - How many free pages an incremental vacuum gives back.
- Journal
Size Limit - How large the WAL file may stay after a checkpoint resets it.
- Judging
- What a write asks of SQLite about a changed row.
- Live
Query Cause - 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.
- Page
Size - A database page size: a power of two from 512 bytes to 64 KiB.
- Recorded
- Whether a statement run through
app_querybelongs 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.
- Secure
Delete - Whether deleted content is overwritten.
- SqlValue
- A value SQLite stores.
- Temp
Store - Where temporary tables and indices are kept.
- Temporary
Directory Error - 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§
- Host
Error - 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.
- Rollback
Join - 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
changescould change whatreadsreturned. PastROWS_PER_TABLErow 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 pastLOOKUP_STEPSand stops leaves sqlive unable to tell, soreadscount as changed whatever the other questions answer (§4). - committing
- The scope of the call committing on this thread.
- enter
- Run
runwith commits made on this thread attributed toscope, if any. - report_
cost - One measured number, as a line
scripts/perf.shreads:COST metric=<name> value=<n> unit=<ms|ratio|count>. Lower is better in every unit. A character inmetricoutside letters, digits and_./-becomes_, so a caller can pass a label unchanged. - report_
time report_costfor 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§
- Column
Set - The table and column names a run read, as pairs.
- Lookups
- Runs one question about a changed row: whether SQLite found a row.
- Policy
Error - The error a connection judged by
Preturns. - 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.