pub struct HostSql<P: Policy> { /* private fields */ }Expand description
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.
Implementations§
Source§impl<P: Policy> HostSql<P>
impl<P: Policy> HostSql<P>
Sourcepub fn bulk_write<F, R, E>(&mut self, sql: F) -> Result<R, E>
pub fn bulk_write<F, R, E>(&mut self, sql: F) -> Result<R, E>
Run sql, the app’s bulk write, in a write transaction with no
pre-update hook. The policy judges its statements in the bulk scope,
and live queries learn only which tables it changed.
Source§impl<P: Policy> HostSql<P>
impl<P: Policy> HostSql<P>
Sourcepub fn live_read<F, R, E>(
&self,
judge: &mut dyn FnMut(ReadSet, &mut Lookups<'_>) -> Result<()>,
read: F,
) -> Result<R, E>
pub fn live_read<F, R, E>( &self, judge: &mut dyn FnMut(ReadSet, &mut Lookups<'_>) -> Result<()>, read: F, ) -> Result<R, E>
A live query’s run on one snapshot. What its statements read goes
to judge before the snapshot ends, which judges the writes that
committed during the run by lookups in that snapshot (§4).
Source§impl<P: Policy> HostSql<P>
impl<P: Policy> HostSql<P>
Sourcepub fn release_memory(&self) -> Result<()>
pub fn release_memory(&self) -> Result<()>
Give back the cached pages no statement is using, as
sqlite3_db_release_memory does. Pages a transaction in progress
changed and hasn’t written out stay; the next read loads what it needs
again.
Source§impl<P: Policy> HostSql<P>
impl<P: Policy> HostSql<P>
Sourcepub fn read_snapshot<F, R, E>(&self, read: F) -> Result<R, E>
pub fn read_snapshot<F, R, E>(&self, read: F) -> Result<R, E>
A one-shot read of one snapshot. Nothing runs it again, so it records nothing of what it reads, and narrows nothing (§4).
Sourcepub fn read_transaction<R, E: From<PolicyError<P>>>(
&self,
read: impl FnOnce() -> Result<R, E>,
) -> Result<R, E>
pub fn read_transaction<R, E: From<PolicyError<P>>>( &self, read: impl FnOnce() -> Result<R, E>, ) -> Result<R, E>
Run read in a read transaction, which rolls back however read
ends.
Sourcepub fn discarded_transaction<T, E: RollbackJoin<P::Failure, P::Refusal>>(
&self,
run: impl FnOnce(&Self) -> Result<T, E>,
) -> Result<T, E>
pub fn discarded_transaction<T, E: RollbackJoin<P::Failure, P::Refusal>>( &self, run: impl FnOnce(&Self) -> Result<T, E>, ) -> Result<T, E>
Run checks that write scratch state, such as temporary tables, in a transaction that always rolls back, so nothing they write is kept or observed. It takes no write lock until something writes the main schema.
Sourcepub fn discarded_write_transaction<T, E: RollbackJoin<P::Failure, P::Refusal>>(
&self,
run: impl FnOnce(&Self) -> Result<T, E>,
) -> Result<T, E>
pub fn discarded_write_transaction<T, E: RollbackJoin<P::Failure, P::Refusal>>( &self, run: impl FnOnce(&Self) -> Result<T, E>, ) -> Result<T, E>
A discarded transaction, as Self::discarded_transaction runs,
that takes the write lock as it begins, for a test’s check that
writes the main schema after reading it. SQLite never waits for the
write lock a transaction already reading asks for: it fails at once
with SQLITE_BUSY if another connection holds it even for a moment,
where BEGIN IMMEDIATE waits out the busy timeout.
Source§impl<P: Policy> HostSql<P>
impl<P: Policy> HostSql<P>
Read the schema cookie once until the returned scope drops. The caller’s transaction runs no DDL.
Source§impl<P: Policy> HostSql<P>
impl<P: Policy> HostSql<P>
Sourcepub fn profiled_statements(&self) -> Vec<ProfiledStatement>
pub fn profiled_statements(&self) -> Vec<ProfiledStatement>
The statements the last profile saw, in the order they ran.
Source§impl<P: Policy> HostSql<P>
impl<P: Policy> HostSql<P>
Sourcepub fn write_with<A, T, E: RollbackJoin<P::Failure, P::Refusal>>(
&mut self,
app: impl FnOnce(&HostSql<P>, &dyn Fn() -> Vec<Operation>) -> Result<A, E>,
host: impl FnOnce(&HostSql<P>, &[Operation], A) -> Result<T, E>,
) -> Result<T, E>
pub fn write_with<A, T, E: RollbackJoin<P::Failure, P::Refusal>>( &mut self, app: impl FnOnce(&HostSql<P>, &dyn Fn() -> Vec<Operation>) -> Result<A, E>, host: impl FnOnce(&HostSql<P>, &[Operation], A) -> Result<T, E>, ) -> Result<T, E>
Run app while the pre-update hook keeps each operation on the
recorded tables, then host with those operations under a session,
judge the live queries, commit and tell the subscriptions. app gets
a call that returns the operations so far. host gets what app
returned.
Sourcepub fn stream_then_write<S, A, E: RollbackJoin<P::Failure, P::Refusal>>(
&mut self,
stream: impl FnOnce(&HostSql<P>) -> Result<(S, bool), E>,
app: impl FnOnce(&HostSql<P>, &dyn Fn() -> Vec<Operation>) -> Result<A, E>,
host: impl FnOnce(&HostSql<P>, &[Operation], A) -> Result<(), E>,
) -> Result<S, E>
pub fn stream_then_write<S, A, E: RollbackJoin<P::Failure, P::Refusal>>( &mut self, stream: impl FnOnce(&HostSql<P>) -> Result<(S, bool), E>, app: impl FnOnce(&HostSql<P>, &dyn Fn() -> Vec<Operation>) -> Result<A, E>, host: impl FnOnce(&HostSql<P>, &[Operation], A) -> Result<(), E>, ) -> Result<S, E>
A streamed transaction, as Self::stream_transaction runs one, in
which stream says whether write_with’s phases follow in the same
transaction. When they do, the app phase takes the hook the stream’s
capture held, which has seen every change of stream; both commit, or
neither.
Source§impl<P: Policy> HostSql<P>
impl<P: Policy> HostSql<P>
Sourcepub fn fail_at(&self, name: &str, event: &str, message: &str)
pub fn fail_at(&self, name: &str, event: &str, message: &str)
Fail each statement that fires event with message, through a
trigger named name.
Sourcepub fn set_value_limit(&self, bytes: i32) -> i32
pub fn set_value_limit(&self, bytes: i32) -> i32
Set the most bytes a string or BLOB can hold on this connection, returning the limit it had.
Sourcepub fn crash_after_next_commit(&mut self)
pub fn crash_after_next_commit(&mut self)
End the process with status 86 as the next commit writes the WAL.
Sourcepub fn panic_next_function(&self)
pub fn panic_next_function(&self)
Panic in the next call of one of the host’s SQL functions on this connection.
Panic in the next judgment of this connection’s authorizer.
Sourcepub fn panic_in_next_hook(&self)
pub fn panic_in_next_hook(&self)
Panic in the next call of a write transaction’s hook on this connection.
Sourcepub fn refuse_transaction_end(&mut self, refuse: bool)
pub fn refuse_transaction_end(&mut self, refuse: bool)
Have the authorizer refuse every COMMIT and ROLLBACK when refuse is
true.
Sourcepub fn crash_after(&self, table: &str, action: &str)
pub fn crash_after(&self, table: &str, action: &str)
End the process with status 86 after each action on table.
Source§impl<P: Policy> HostSql<P>
impl<P: Policy> HostSql<P>
Sourcepub fn test_track_work(&self, counter: ConnectionWorkCounter)
pub fn test_track_work(&self, counter: ConnectionWorkCounter)
Count this connection’s work into counter from now on.
Sourcepub fn test_record_statements(&self, log: StatementLog)
pub fn test_record_statements(&self, log: StatementLog)
Record the statements this connection’s reads run into log from
now on.
Sourcepub fn open(
path: &Path,
read_only: bool,
policy: P,
whole_views: Arc<WholeViews>,
settings: &SqliteSettings,
setup: &dyn Fn(&Setup<'_, P>, &P) -> Result<()>,
) -> Result<Self, PolicyError<P>>
pub fn open( path: &Path, read_only: bool, policy: P, whole_views: Arc<WholeViews>, settings: &SqliteSettings, setup: &dyn Fn(&Setup<'_, P>, &P) -> Result<()>, ) -> Result<Self, PolicyError<P>>
A connection to the database at path, for reading only when
read_only, whose authorizer asks policy after its own rules and
treats whole_views as a live query’s whole reads. setup registers
what the connection needs, given its policy, before any SQL runs.
Sourcepub fn function_argument_limit(&self) -> Result<usize, PolicyError<P>>
pub fn function_argument_limit(&self) -> Result<usize, PolicyError<P>>
The most arguments an SQL function call can pass on this connection.
Sourcepub fn length_limit(&self) -> Result<i32>
pub fn length_limit(&self) -> Result<i32>
The most bytes a string or BLOB can hold on this connection.
Sourcepub fn open_blob(
&self,
table: &str,
column: &str,
rowid: i64,
read_only: bool,
) -> Result<Blob<'_>>
pub fn open_blob( &self, table: &str, column: &str, rowid: i64, read_only: bool, ) -> Result<Blob<'_>>
Open the BLOB in column of the row rowid of the main schema’s
table, for reading only when read_only.
Sourcepub fn fail_handle(&self, failure: P::Failure)
pub fn fail_handle(&self, failure: P::Failure)
Fail the handle this connection serves with failure, so every later
call and live query reports it. A connection that serves no handle
yet fails nothing.
Sourcepub fn within<T>(&self, scope: P::Scope, run: impl FnOnce() -> T) -> T
pub fn within<T>(&self, scope: P::Scope, run: impl FnOnce() -> T) -> T
Run run with this connection’s policy in scope, leaving the scope
on every path out of run, a panic’s included.
Sourcepub fn refresh_policy(&self, extent: Refresh) -> Result<()>
pub fn refresh_policy(&self, extent: Refresh) -> Result<()>
Have this connection’s policy read the schema again (Policy::refresh).
Sourcepub fn read_only(&self) -> Result<bool>
pub fn read_only(&self) -> Result<bool>
Whether SQLite opened the main database for reading only.
Sourcepub fn observes_commits(&self) -> bool
pub fn observes_commits(&self) -> bool
Whether this connection is a writer that observes its commits.
Sourcepub fn with_profile<T>(&mut self, run: impl FnOnce(&mut Self) -> T) -> T
pub fn with_profile<T>(&mut self, run: impl FnOnce(&mut Self) -> T) -> T
Run run on this connection. Tests trace its statements, ending the
profile on every path out of run, a panic’s included, so a profile
is never left open; one inside another nests (sqlite_tests.rs).
Sourcepub fn batch(&self, sql: &str) -> Result<(), PolicyError<P>>
pub fn batch(&self, sql: &str) -> Result<(), PolicyError<P>>
Run the host’s own statements in sql, one after another.
Sourcepub fn column_collation(
&self,
table: &str,
column: &str,
) -> Result<String, PolicyError<P>>
pub fn column_collation( &self, table: &str, column: &str, ) -> Result<String, PolicyError<P>>
The collation a column declares, BINARY when it names none.
Sourcepub fn reads(&self, sql: &str) -> Result<StatementReads, PolicyError<P>>
pub fn reads(&self, sql: &str) -> Result<StatementReads, PolicyError<P>>
The columns sql reads and the functions it calls, as SQLite
resolves them while preparing it; it never runs.
Sourcepub fn execute<Q: Params>(
&self,
sql: &str,
params: Q,
) -> Result<usize, PolicyError<P>>
pub fn execute<Q: Params>( &self, sql: &str, params: Q, ) -> Result<usize, PolicyError<P>>
Run the host’s own statement sql with params, returning the rows
it changed.
Sourcepub fn query_row<T, Q: Params>(
&self,
sql: &str,
params: Q,
map: impl FnOnce(&Row<'_>) -> Result<T>,
) -> Result<T, PolicyError<P>>
pub fn query_row<T, Q: Params>( &self, sql: &str, params: Q, map: impl FnOnce(&Row<'_>) -> Result<T>, ) -> Result<T, PolicyError<P>>
The first row of the host’s own query sql with params, through
map.
Sourcepub fn query<T, Q: Params>(
&self,
sql: &str,
params: Q,
map: impl FnMut(&Row<'_>) -> Result<T>,
) -> Result<Vec<T>, PolicyError<P>>
pub fn query<T, Q: Params>( &self, sql: &str, params: Q, map: impl FnMut(&Row<'_>) -> Result<T>, ) -> Result<Vec<T>, PolicyError<P>>
Every row of the host’s own query sql with params, through map.
Sourcepub fn for_each<Q: Params, E: From<PolicyError<P>>>(
&self,
sql: &str,
params: Q,
visit: impl FnMut(&Row<'_>) -> Result<(), E>,
) -> Result<(), E>
pub fn for_each<Q: Params, E: From<PolicyError<P>>>( &self, sql: &str, params: Q, visit: impl FnMut(&Row<'_>) -> Result<(), E>, ) -> Result<(), E>
Stream rows to a consumer with its own error type.
Sourcepub fn prepare_host(&self, sql: &str) -> Result<(), PolicyError<P>>
pub fn prepare_host(&self, sql: &str) -> Result<(), PolicyError<P>>
Prepare sql as the host’s own statement, compiling every trigger
it would fire and those they fire in turn, and drop it unrun. What
the authorizer refused in an app trigger it compiles is the error.
Sourcepub fn prepare_app(&self, sql: &str) -> Result<()>
pub fn prepare_app(&self, sql: &str) -> Result<()>
Prepare the app statement sql, judged as an app statement is, and
drop it unrun: what preparing it tells the policy is the result.
Sourcepub fn app_execute<Q: Params>(&self, sql: &str, params: Q) -> Result<usize>
pub fn app_execute<Q: Params>(&self, sql: &str, params: Q) -> Result<usize>
Run the app’s statement sql with params, judged as the app’s,
returning the rows it changed.
Sourcepub fn app_batch(&self, sql: &str) -> Result<()>
pub fn app_batch(&self, sql: &str) -> Result<()>
Run the app’s statements in sql, one after another, each judged as
the app’s.
Sourcepub fn app_batch_each(
&self,
sql: &str,
each: impl FnMut(&str, &mut dyn FnMut() -> Result<()>) -> Result<()>,
) -> Result<()>
pub fn app_batch_each( &self, sql: &str, each: impl FnMut(&str, &mut dyn FnMut() -> Result<()>) -> Result<()>, ) -> Result<()>
Run the app’s statements in sql one at a time, handing each the
text of each as SQLite expanded it and a call that steps it through
its rows. each runs that call once, between whatever it does before
and after the statement.
SQLite’s count of changes to the main schema, read afresh.
Sourcepub fn migrating<T, E: From<PolicyError<P>>>(
&self,
run: impl FnOnce() -> Result<T, E>,
) -> Result<T, E>
pub fn migrating<T, E: From<PolicyError<P>>>( &self, run: impl FnOnce() -> Result<T, E>, ) -> Result<T, E>
Run one migration step inside the open migration transaction. The policy records which tables its statements write as SQLite prepares them (§18.1).
Sourcepub fn app_query_row<T, Q: Params>(
&self,
recorded: Recorded,
sql: &str,
params: Q,
map: impl FnOnce(&Row<'_>) -> Result<T>,
) -> Result<T>
pub fn app_query_row<T, Q: Params>( &self, recorded: Recorded, sql: &str, params: Q, map: impl FnOnce(&Row<'_>) -> Result<T>, ) -> Result<T>
The first row of the app’s query sql with params, through map;
a read’s statement when recorded says so.
Sourcepub fn app_query<T, Q: Params>(
&self,
recorded: Recorded,
sql: &str,
params: Q,
map: impl FnMut(&Row<'_>) -> Result<T>,
) -> Result<Vec<T>>
pub fn app_query<T, Q: Params>( &self, recorded: Recorded, sql: &str, params: Q, map: impl FnMut(&Row<'_>) -> Result<T>, ) -> Result<Vec<T>>
Every row of the app’s query sql with params, through map; a
read’s statement when recorded says so.
Sourcepub fn changed_rows(&self) -> u64
pub fn changed_rows(&self) -> u64
The rows this connection’s statements have changed since it opened, their triggers’ included, as SQLite counts them.
Sourcepub fn write_scope(&self) -> WriteSql<'_, P>
pub fn write_scope(&self) -> WriteSql<'_, P>
The scope in which the app’s write SQL runs.
Sourcepub fn local_scope(&self) -> LocalSql<'_, P>
pub fn local_scope(&self) -> LocalSql<'_, P>
The scope in which app SQL the host runs inside a transaction of its
own writes: the policy judges each statement as in the local scope
(StatementScope::local), and SQLite prepares each afresh. Inside a
bulk write, the tables it changes count among the bulk write’s.
Sourcepub fn require_transaction(&self) -> Result<(), PolicyError<P>>
pub fn require_transaction(&self) -> Result<(), PolicyError<P>>
Refuse with TransactionEnded unless a transaction is open: a
statement may have committed or rolled back the one its caller began.
Sourcepub fn transaction<T, E: RollbackJoin<P::Failure, P::Refusal>>(
&mut self,
run: impl FnOnce(&Self) -> Result<T, E>,
) -> Result<T, E>
pub fn transaction<T, E: RollbackJoin<P::Failure, P::Refusal>>( &mut self, run: impl FnOnce(&Self) -> Result<T, E>, ) -> Result<T, E>
Run run in a write transaction, whose failures are E: a failed
rollback joins the run’s own error.
Sourcepub fn stream_transaction<T, E: RollbackJoin<P::Failure, P::Refusal>>(
&mut self,
run: impl FnOnce(&Self) -> Result<T, E>,
) -> Result<T, E>
pub fn stream_transaction<T, E: RollbackJoin<P::Failure, P::Refusal>>( &mut self, run: impl FnOnce(&Self) -> Result<T, E>, ) -> Result<T, E>
Streaming transfers publish table invalidations without a session’s retained before/after BLOB values growing with the transferred object.
Sourcepub fn close(self) -> Result<(), PolicyError<P>>
pub fn close(self) -> Result<(), PolicyError<P>>
Close the connection, failing if SQLite still holds a statement of it.
Sourcepub fn leave_statement_open(&self)
pub fn leave_statement_open(&self)
Prepare a statement and never finalize it, so SQLite refuses to close
this connection, as it does with SQLITE_BUSY.
Sourcepub fn on_commit_point(&self, callback: impl Fn(CommitPoint) + Send + 'static)
pub fn on_commit_point(&self, callback: impl Fn(CommitPoint) + Send + 'static)
Call callback at each point this connection’s write transactions
pass as they commit, from now on.
Source§impl<P: Policy> HostSql<P>
impl<P: Policy> HostSql<P>
Sourcepub fn sqlite_settings(&self) -> Result<SqliteSettingsInEffect, PolicyError<P>>
pub fn sqlite_settings(&self) -> Result<SqliteSettingsInEffect, PolicyError<P>>
The SQLite settings in effect on this connection.
Sourcepub fn wal_checkpoint(
&self,
mode: CheckpointMode,
) -> Result<WalCheckpoint, PolicyError<P>>
pub fn wal_checkpoint( &self, mode: CheckpointMode, ) -> Result<WalCheckpoint, PolicyError<P>>
Checkpoint the WAL outside any transaction, on a connection in WAL
mode: the writer, or a checkpointer’s own. SQLite reports the frames
unless it read nothing of the WAL, which it reports as busy with no
frames. Every checkpoint sqlive runs on a database, its checkpointer’s
or the host’s, goes through here. After each one that read the WAL,
except a Noop, which copies nothing, this connection sends the main
file’s size to the database’s watch, when it holds the watch
(Database::checkpointed_size).
Sourcepub fn incremental_vacuum(
&self,
pages: IncrementalVacuum,
) -> Result<(), PolicyError<P>>
pub fn incremental_vacuum( &self, pages: IncrementalVacuum, ) -> Result<(), PolicyError<P>>
Give back free pages of an incrementally vacuumed database. SQLite frees one page per result row, so every row is stepped.
Sourcepub fn give_back_free_pages(&self) -> Result<(), PolicyError<P>>
pub fn give_back_free_pages(&self) -> Result<(), PolicyError<P>>
Give back the free pages of an incrementally vacuumed database past the 4 MiB sqlive leaves for later writes to reuse; any other auto-vacuum mode is the app’s choice and keeps its meaning.