Skip to main content

HostSql

Struct HostSql 

Source
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>

Source

pub fn bulk_write<F, R, E>(&mut self, sql: F) -> Result<R, E>
where E: RollbackJoin<P::Failure, P::Refusal>, F: FnOnce(&Self) -> 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>

Source

pub fn live_read<F, R, E>( &self, judge: &mut dyn FnMut(ReadSet, &mut Lookups<'_>) -> Result<()>, read: F, ) -> Result<R, E>
where F: FnOnce(&Self) -> Result<R, E>, E: From<PolicyError<P>>,

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>

Source

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>

Source

pub fn read_snapshot<F, R, E>(&self, read: F) -> Result<R, E>
where F: FnOnce(&Self) -> Result<R, E>, E: From<PolicyError<P>>,

A one-shot read of one snapshot. Nothing runs it again, so it records nothing of what it reads, and narrows nothing (§4).

Source

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.

Source

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.

Source

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>

Read the schema cookie once until the returned scope drops. The caller’s transaction runs no DDL.

Source§

impl<P: Policy> HostSql<P>

Source

pub fn profiled_statements(&self) -> Vec<ProfiledStatement>

The statements the last profile saw, in the order they ran.

Source§

impl<P: Policy> HostSql<P>

Source

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.

Source

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>

Source

pub fn fail_at(&self, name: &str, event: &str, message: &str)

Fail each statement that fires event with message, through a trigger named name.

Source

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.

Source

pub fn crash_after_next_commit(&mut self)

End the process with status 86 as the next commit writes the WAL.

Source

pub fn panic_next_function(&self)

Panic in the next call of one of the host’s SQL functions on this connection.

Source

pub fn panic_next_authorization(&self)

Panic in the next judgment of this connection’s authorizer.

Source

pub fn panic_in_next_hook(&self)

Panic in the next call of a write transaction’s hook on this connection.

Source

pub fn refuse_transaction_end(&mut self, refuse: bool)

Have the authorizer refuse every COMMIT and ROLLBACK when refuse is true.

Source

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>

Source

pub fn test_track_work(&self, counter: ConnectionWorkCounter)

Count this connection’s work into counter from now on.

Source

pub fn test_record_statements(&self, log: StatementLog)

Record the statements this connection’s reads run into log from now on.

Source

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.

Source

pub fn function_argument_limit(&self) -> Result<usize, PolicyError<P>>

The most arguments an SQL function call can pass on this connection.

Source

pub fn length_limit(&self) -> Result<i32>

The most bytes a string or BLOB can hold on this connection.

Source

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.

Source

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.

Source

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.

Source

pub fn refresh_policy(&self, extent: Refresh) -> Result<()>

Have this connection’s policy read the schema again (Policy::refresh).

Source

pub fn read_only(&self) -> Result<bool>

Whether SQLite opened the main database for reading only.

Source

pub fn observes_commits(&self) -> bool

Whether this connection is a writer that observes its commits.

Source

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).

Source

pub fn batch(&self, sql: &str) -> Result<(), PolicyError<P>>

Run the host’s own statements in sql, one after another.

Source

pub fn column_collation( &self, table: &str, column: &str, ) -> Result<String, PolicyError<P>>

The collation a column declares, BINARY when it names none.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn app_batch(&self, sql: &str) -> Result<()>

Run the app’s statements in sql, one after another, each judged as the app’s.

Source

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.

Source

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).

Source

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.

Source

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.

Source

pub fn changed_rows(&self) -> u64

The rows this connection’s statements have changed since it opened, their triggers’ included, as SQLite counts them.

Source

pub fn write_scope(&self) -> WriteSql<'_, P>

The scope in which the app’s write SQL runs.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn close(self) -> Result<(), PolicyError<P>>

Close the connection, failing if SQLite still holds a statement of it.

Source

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.

Source

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>

Source

pub fn sqlite_settings(&self) -> Result<SqliteSettingsInEffect, PolicyError<P>>

The SQLite settings in effect on this connection.

Source

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).

Source

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.

Source

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.

Auto Trait Implementations§

§

impl<P> !Freeze for HostSql<P>

§

impl<P> !RefUnwindSafe for HostSql<P>

§

impl<P> !Sync for HostSql<P>

§

impl<P> !UnwindSafe for HostSql<P>

§

impl<P> Send for HostSql<P>

§

impl<P> Unpin for HostSql<P>

§

impl<P> UnsafeUnpin for HostSql<P>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more