Struct SqlEngine 

pub struct SqlEngine<S> { /* private fields */ }

Runs SQL statements against a wasm-dbms database.

The engine holds the database schema and nothing else. It does not borrow the DbmsContext: the context is passed to every execute call, so one engine can serve several contexts and can be stored next to its context, for example in a thread_local!.

Transactions

Transactions are addressed by their TransactionId, the same ids that DbmsContext::begin_transaction returns. BEGIN opens a transaction and returns its id in SqlResult::TxBegin; passing that id to later calls runs them inside the transaction, where they see its uncommitted writes. COMMIT and ROLLBACK close the transaction whose id they receive. A statement that fails leaves the transaction open. Calls without an id are applied immediately and do not see open transactions.

The engine does not check who holds an id. An application layer that serves several identities keeps its own ledger from id to identity and checks it before calling execute with that id.

Examples

use wasm_dbms::prelude::*;
use wasm_dbms_api::prelude::*;
use wasm_dbms_memory::prelude::HeapMemoryProvider;
use wasm_dbms_sql::SqlEngine;

#[derive(Clone, DatabaseSchema)]
#[tables(User = "users")]
pub struct MySchema;

let ctx = DbmsContext::new(HeapMemoryProvider::default());
MySchema::register_tables(&ctx)?;
let engine = SqlEngine::new(MySchema);

engine.execute(
    &ctx,
    None,
    "INSERT INTO users (id, name) VALUES (?, ?)",
    &[Value::from(1u32), Value::from("Alice")],
)?;

let SqlResult::TxBegin(tx) = engine.execute(&ctx, None, "BEGIN", &[])? else {
    unreachable!("BEGIN returns TxBegin");
};
engine.execute(&ctx, Some(tx), "UPDATE users SET name = 'Alicia' WHERE id = 1", &[])?;
engine.execute(&ctx, Some(tx), "COMMIT", &[])?;

Implementations

impl<S> SqlEngine<S>

pub fn new(schema: S) -> Self

Creates an engine for the tables of schema.

pub fn execute<'ctx, M>( &self, ctx: &'ctx DbmsContext<M>, tx: Option<TransactionId>, sql: &str, params: &[Value], ) -> Result<SqlResult, SqlError>

where M: MemoryProvider, S: DatabaseSchema<M> + Clone + 'ctx,

Parses and runs one SQL statement, outside or inside a transaction.

tx selects where the statement runs: None applies it immediately through WasmDbmsDatabase::oneshot, Some(id) runs it through WasmDbmsDatabase::from_transaction. BEGIN requires None and returns the new id in SqlResult::TxBegin; COMMIT and ROLLBACK require Some(id). params supplies one value per ? placeholder, in order.

Errors

• SqlError::Parse and SqlError::MissingWhereClause when sql is not a valid statement.
• SqlError::ParameterCountMismatch when params does not have one value per placeholder.
• SqlError::UnknownTable, SqlError::UnknownColumn, and SqlError::AmbiguousColumn when a name does not resolve.
• SqlError::TypeMismatch and SqlError::InvalidLiteral when a value cannot be converted to the type of its column.
• SqlError::Unsupported when the statement combines features the DBMS cannot run together.
• SqlError::TransactionAlreadyActive for BEGIN with Some(id).
• SqlError::NoActiveTransaction for COMMIT or ROLLBACK with None.
• SqlError::Runtime when the DBMS rejects the operation, for example on a constraint violation, or when id does not name an open transaction.

Trait Implementations

impl<S> Debug for SqlEngine<S>

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

Formats the value using the given formatter.