Struct Sqlite 

pub struct Sqlite;

SQLite: backtick-quoted names, ? placeholders, rows claimed by lease.

It builds the statements of the lease form (Lease), of the advisory lock form (Advisory), and the insert. A writer locks the whole database, not rows, so it builds no claim that holds rows for a handler: it does not implement RowLock, and a SQLite table declares locked_until or advisory_lock. A lease claim is one update that writes the lease, counts the attempt and returns the rows it took, as they were before; one writer at a time keeps two claims apart. The rows of one claim come back in no particular order. A dead letter into a table copies the row, then deletes it, in one transaction. A claim of the service’s own opens its transaction with BEGIN IMMEDIATE (begin_lease_claim), so it takes the write lock before it selects. Every name is quoted, so a name keeps its case and may hold any character, and SQLite keeps a name of any length. The quotes are backticks, which SQLite always reads as a name: a statement that names a column the table lacks fails when it is prepared. fetch is refused, so a claim of the service’s own brings a fetch of its own.

SQLite keeps times as text, so the statements compare times as text: two times compare right when their text sorts as the times do.

SQLite has no locks a session holds, so in the advisory lock form the broker keeps the keys in work in the process: lock and unlock are None, and the claim selects up to Param::Limit claimable rows in claim order with their keys, the text the key’s parts render, a column without a value read as empty text. The select cannot leave out the keys in work, so the broker binds a limit that reaches past them. The take counts the attempt and returns the row in one statement.

A table with FIFO groups needs no guard (fifo_guard is None): one writer at a time keeps two claims apart, and a lease claim takes nothing while a row of the group holds a lease.

SQLite runs every transaction serializable, so a table names no isolation level here: it names a mode, and its transactions open with BEGIN DEFERRED, BEGIN IMMEDIATE or BEGIN EXCLUSIVE (begin), or with BEGIN where it names none.

Examples

A subscription asks SQLite for the statements of its table, as ruststream-sqlx does when the subscription starts:

use ruststream_sqlx_dialect::{
    Advisory, Column, Form, KeyPart, Sqlite, Statement, StatementError, TableSpec,
};

// The jobs table as `#[derive(Inbox)]` describes it, with `advisory_lock = "jobs-{job_id}"`.
const JOBS: TableSpec<'static> = TableSpec::new(
    "jobs",
    Column::new("job_id"),
    Form::Advisory(&[KeyPart::Literal("jobs-"), KeyPart::Column("job_id")]),
);

// What a subscription to an advisory lock table prepares: the claim of candidates, and the
// lock on a key where the database keeps locks; without one the broker keeps the keys in work
// in the process.
fn advisory_statements(
    dialect: &impl Advisory,
    spec: &TableSpec<'_>,
) -> Result<(Statement, Option<Statement>), StatementError> {
    Ok((dialect.advisory_claim(spec)?, dialect.lock()))
}

fn main() -> Result<(), StatementError> {
    // SQLite keeps no locks a session holds, so the process keeps the keys in work.
    let (_claim, lock) = advisory_statements(&Sqlite, &JOBS)?;
    assert!(lock.is_none());
    Ok(())
}

A table in the row lock form finds no claim here, so a subscription to one does not compile:

use ruststream_sqlx_dialect::{
    ClaimShape, Column, Form, RowLock, Sqlite, Statement, StatementError, TableSpec,
};

const JOBS: TableSpec<'static> = TableSpec::new("jobs", Column::new("job_id"), Form::RowLock);

// What a subscription to a row lock table asks of its dialect.
fn claims_its_rows(dialect: &impl RowLock) -> Result<Statement, StatementError> {
    dialect.lock_claim(&JOBS, ClaimShape::Rows)
}

let claim = claims_its_rows(&Sqlite);

Trait Implementations

impl Advisory for Sqlite

fn advisory_claim( &self, spec: &TableSpec<'_>, ) -> Result<Statement, StatementError>

The candidates: up to Param::Limit claimable rows of the subscription’s group in claim order, two columns each, the id and the lock key as text (named __lock). It takes no lock and writes nothing; where the database can tell, it leaves out the rows whose key another session holds.

fn lock(&self) -> Option<Statement>

Tries the lock on Param::Key for the session, without waiting: one row whose first column is a 64-bit integer, nonzero when the lock was taken. None when the process keeps the locks.

fn unlock(&self) -> Option<Statement>

Releases the lock on Param::Key: one row whose first column is a 64-bit integer, nonzero when the session held it. None when the process keeps the locks.

fn take( &self, spec: &TableSpec<'_>, shape: ClaimShape, ) -> Result<Vec<Statement>, StatementError>

The statements that take a candidate whose lock the session holds: they count its attempt where the table has one and read the row again in shape, as it was before the count, only while it is still claimable. The last returns the row, or none when the row is gone or no longer claimable; a first statement, where there are two, counts the attempt and changes no row in that case.

impl Clone for Sqlite

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Sqlite

impl Debug for Sqlite

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Sqlite

fn default() -> Self

Returns the “default value” for a type.

impl Dialect for Sqlite

fn name(&self) -> &'static str

The dialect’s name, for messages.

fn quote_into(&self, ident: &str, out: &mut String)

Appends ident to out, quoted as a name of this database.

fn placeholder_into(&self, _: NonZeroUsize, out: &mut String)

Appends the placeholder of parameter number index (counted from 1) to out.

fn fetch(&self, _: &TableSpec<'_>) -> Result<Statement, StatementError>

The statement that reads the rows of claimed ids, bound as one list.

fn ack(&self, spec: &TableSpec<'_>) -> Result<Statement, StatementError>

The statement that acknowledges a row: it deletes the row, or sets processed_at when the table has that column.

fn retry( &self, spec: &TableSpec<'_>, ) -> Result<Option<Statement>, StatementError>

The statement that releases a row for another attempt at once, or None when releasing the row needs no statement.

fn retry_after(&self, spec: &TableSpec<'_>) -> Result<Statement, StatementError>

The statement that releases a row for another attempt after a delay, bound as Param::RetryAfter.

fn discard(&self, spec: &TableSpec<'_>) -> Result<Statement, StatementError>

The statement that drops a row: it deletes the row, or sets processed_at when the table has that column.

fn dead_letter_group( &self, spec: &TableSpec<'_>, ) -> Result<Statement, StatementError>

The statement that moves a row whose attempts are spent to another group, bound as Param::Destination.

fn dead_letter_table( &self, spec: &TableSpec<'_>, target: TableName<'_>, ) -> Result<Vec<Statement>, StatementError>

The statements that move a row whose attempts are spent to target, a table with the same columns; they run in one transaction.

fn insert(&self, spec: &TableSpec<'_>) -> Result<Statement, StatementError>

The statement that inserts a row: every column the database does not fill, in the order of TableSpec::columns, each bound as Param::Column.

fn begin( &self, opening: Opening, ) -> Result<Option<&'static str>, StatementError>

The statement that opens a transaction at opening in place of BEGIN, or None when BEGIN opens it.

fn server_version(&self) -> Option<&'static str>

The query that reads the server’s version as one text column, or None when the dialect’s statements run on every version of its server.

fn check_server( &self, spec: &TableSpec<'_>, version: &str, ) -> Result<(), StatementError>

Refuses a server older than the statements of spec need; version is what the server_version query returned.

fn savepoint(&self) -> &'static str

The statement that sets the savepoint after a claim, inside the claim’s transaction: what a handler writes after it can be discarded while the claim’s own work stays.

fn rollback_to_savepoint(&self) -> &'static str

The statement that discards what the transaction did after savepoint, and keeps the transaction open.

fn fifo_guard( &self, spec: &TableSpec<'_>, ) -> Result<Option<Statement>, StatementError>

The statement a claim of a table with FIFO groups runs first in its transaction, to take the subscription’s group for it; None for a table without FIFO groups, or a dialect that takes no group.

impl Eq for Sqlite

impl Hash for Sqlite

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Lease for Sqlite

fn lease_claim( &self, spec: &TableSpec<'_>, shape: ClaimShape, ) -> Result<Statement, StatementError>

The statement that claims up to Param::Limit rows of the subscription’s group, in claim order, among the rows whose lease ended by Param::LeaseNow.

fn extend(&self, spec: &TableSpec<'_>) -> Result<Statement, StatementError>

The statement that extends a delivery’s lease: it writes the new expiry (Param::Lease) while the row still holds the delivery’s token (Param::Held), so a handler that runs longer than one lease keeps its row.

fn stamp(&self, spec: &TableSpec<'_>) -> Result<Statement, StatementError>

The statement that leases one claimed row: it writes the expiry (Param::Lease) and counts the attempt, while no lease holds the row at Param::LeaseNow.

fn claim_counts_attempt(&self, spec: &TableSpec<'_>) -> bool

Whether the rows the lease claim of spec returns carry the attempt the claim counted. A dialect whose claim returns the rows as they were before answers false; where it answers true, a delivery reports one less than its row carries.

fn begin_lease_claim(&self) -> Option<&'static str>

The statement that opens the transaction of a claim that only selects its rows, in place of BEGIN, or None when BEGIN opens it.

fn claim_writes_lease(&self) -> bool

Whether the lease claim writes the lease itself. A dialect whose lease claim only selects the rows answers false, and the claim’s transaction then runs stamp for each claimed row before it commits.

impl Opens<Deferred> for Sqlite

impl Opens<Exclusive> for Sqlite

impl Opens<Immediate> for Sqlite

impl OutboxDialect for Sqlite

fn outbox_fetch( &self, spec: &TableSpec<'_>, ) -> Result<Statement, StatementError>

The statement that reads the record Param::Id names while it is unprocessed, with every column: what the consumer of a tracked message takes into work.

fn outbox_mark(&self, spec: &TableSpec<'_>) -> Result<Statement, StatementError>

The statement that marks the record Param::Id names processed: it sets processed_at to now, or deletes the record in a table without that column.

fn outbox_recover( &self, spec: &TableSpec<'_>, ) -> Result<Statement, StatementError>

The statement that reads the unprocessed records published under the name Param::Group binds, with every column: what the republish at startup sends again.

impl PartialEq for Sqlite

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Sqlite