Struct SqlContext 

pub struct SqlContext<'connection, 'write> { /* private fields */ }

App SQL inside one local write, and coven’s steps beside it (§4). Returning an error rolls back every statement and step. This borrowed context cannot change the transaction or access coven’s tables.

Implementations

impl<'connection, 'write> SqlContext<'connection, 'write>

pub fn move_to_cloud(&self, files: Vec<MoveFile>) -> Result<MoveId, DbError>

Record a move of these files of this device, on it only, to the cloud (§17.3). It survives restarts; once every file is stored, one write switches them all to the cloud, changing no app row.

pub fn cancel_move(&self, id: MoveId) -> Result<(), DbError>

Cancel a recorded move: every file stays on this device only, and the move’s record ends (§17.3).

pub fn unpin(&self, files: &[FileId]) -> Result<(), DbError>

Remove these files’ copies from this device in this write: every cache entry of their stored bytes, pinned or not, the partial download a pin left, and the pin requests coven keeps for them (§17.8). Nothing else is evicted. A file this device has no record of, or one on one device only, has nothing to remove. The bytes go once the write has committed.

pub fn evict_file(&self, file: FileId) -> Result<(), DbError>

Remove a stored file’s cached copies, pinned or not, in this write, with no storage operation (§17.8). A file this device has no record of, or one on one device only, has none. The bytes go once the write has committed.

pub fn clear_cache(&self, namespace: &str) -> Result<(), DbError>

Clear a declared namespace’s cache in this write (§17.8): every unpinned file and chunk goes. Pinned copies, the partial downloads pins left and other namespaces stay. An undeclared namespace fails with UndeclaredNamespace. The bytes go once the write has committed.

pub fn set_cache_budget( &self, namespace: &str, bytes: u64, ) -> Result<(), DbError>

Set a declared namespace’s cache budget and evict its unpinned entries until they are within it, in this write (§17.8). Pinned bytes don’t count toward the budget. An undeclared namespace fails with UndeclaredNamespace. The evicted bytes go once the write has committed.

pub fn dismiss_lost_values(&self, values: &[LostValue]) -> Result<(), DbError>

Dismiss lost values the app has dealt with, in this write (§8.4): its record carries the acknowledgements and the removed rows’ deletes, with their cascades, after the app’s own changes, so every device drops them. A removed row is deleted for good. A value no longer lost as it was, such as a row restored since, is left alone. The write fails with DismissedRowChanged if it also changes a row its dismissals delete.

pub fn set_uploads_paused(&self, paused: bool) -> Result<(), DbError>

Pause trailing uploads, or resume them, in this write (§17.9). A paused upload keeps its place and its provider session.

pub fn set_unmetered_only(&self, unmetered_only: bool) -> Result<(), DbError>

Move files only on unmetered networks, or on any, in this write (§17.9).

pub fn after_commit(&self, effect: impl FnOnce() + 'static)

Run effect once this write has committed, as the in-memory side of one of coven’s steps: nothing runs for a write that rolls back. The write returns only once every effect has run.

pub fn put_staged<T>(&self, staged: StagedFiles<T>) -> Result<T, DbError>

Put files stage_files staged into this write, and return what its batch returned, such as their ids, for this write’s rows to name (§17.2). Files staged by another open store, or by this one before it closed, fail with PreparedElsewhere. A file no row names fails the write with FileUnreferenced.

pub fn put_user_file( &self, namespace: &str, original: PreparedUserFile, place: Place, ) -> Result<FileId, DbError>

Stage a user’s original, read whole once already, as a new file in a user namespace, and return its id for a row to reference (§17.1, §17.3). Coven records the original’s path, size, modification time and the hashes its read found; it never reads it here. An undeclared namespace fails with UndeclaredNamespace, an app one with NamespaceKind.

pub fn existing_file(&self, from: FileId) -> FileId

Stage a new file over an existing file’s bytes, for a row in any audience, and return its id (§17.2). The write fails with FileAbsent if this device has no record of from, and with NotThisDevice if from is on another device only.

pub fn pin(&self, prepared: PreparedPin) -> Result<(), DbError>

Pin a prepared pin’s files in this write (§17.8): each whole copy becomes the file’s pinned cache entry, and each copy already kept stays. Files prepared in another open store, or in this one before it closed, fail with PreparedElsewhere; a file whose record left its stored bytes since with NoLongerStored; and a kept copy evicted or unpinned since with PinChanged.

pub fn make_device_only( &self, prepared: PreparedDeviceOnly, ) -> Result<(), DbError>

Switch a prepared call’s files to device-only on this device, each to its copy, which becomes the original this device records, in this write (§17.3). Each must still be one this device may make device-only, and still stored where its copy came from (NotInCloud); copies prepared in another open store, or in this one before it closed, fail with PreparedElsewhere. A write that also removes such a file’s last reference fails with DeviceOnlyUnreferenced.

pub fn acknowledge_operation( &self, operation: OperationId, ) -> Result<(), DbError>

Acknowledge a finished operation the app’s writes journaled, in this write: it leaves coven_operations (§11.4). One still running fails with OperationRunning; one not listed there with OperationUnknown.

pub fn acknowledge_joined_invitee(&self) -> Result<(), DbError>

End the new person’s name the store a join published keeps, in this write, which records the app’s profile of that person, or its request for one (§13.2). With no name kept, it changes nothing.

pub fn journal_step<T, E>( &self, step: impl FnOnce(&Journal<'_>) -> Result<T, E>, ) -> Result<T, E>

Run one of sync’s steps on the journal in this write (§4, §11). A failed step fails the write, even if the closure goes on and returns success, since it may have made only part of its change.

pub fn execute<P: Params>(&self, sql: &str, params: P) -> Result<usize>

Execute one app statement with parameters.

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

Execute app statements within this write’s transaction.

pub fn query_row<T, P, F>(&self, sql: &str, params: P, map: F) -> Result<T>

where P: Params, F: FnOnce(&Row<'_>) -> Result<T>,

Map one app row, including changes already made by this write.

pub fn query<T, P, F>(&self, sql: &str, params: P, map: F) -> Result<Vec<T>>

where P: Params, F: FnMut(&Row<'_>) -> Result<T>,

Map all app rows produced by a query within this write.

Trait Implementations

impl SqlRead for SqlContext<'_, '_>

fn query_row<T, P, F>(&self, sql: &str, params: P, map: F) -> Result<T>

where P: Params, F: FnOnce(&Row<'_>) -> Result<T>,

Map the first result row.

fn query<T, P, F>(&self, sql: &str, params: P, map: F) -> Result<Vec<T>>

where P: Params, F: FnMut(&Row<'_>) -> Result<T>,

Map all result rows.