Struct Transaction

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

Transaction can be used to query and update the database.

From the perspective of a Transaction each other Transaction is fully applied or not at all. Futhermore, the effects of Transactions have a global order. So if we have mutations A and then B, it is impossible for a Transaction to see the effect of B without seeing the effect of A.

Implementations

impl<S> Transaction<S>

pub fn query<F, R>(&self, f: F) -> R

where F: for<'inner> FnOnce(&mut Query<'inner, S>) -> R,

Execute a query with multiple results.

let user_names = txn.query(|rows| {
    let user = rows.join(User);
    rows.into_vec(&user.name)
});
assert_eq!(user_names, vec!["Alice".to_owned()]);

pub fn query_one<O: 'static>( &self, val: impl IntoSelect<'static, S, Out = O>, ) -> O

Retrieve a single result from the database.

let res = txn.query_one("test".into_expr());
assert_eq!(res, "test");

Instead of using Self::query_one in a loop, it is better to call Self::query and return all results at once.

impl<S: 'static> Transaction<S>

pub fn insert<T: Table<Schema = S>>( &mut self, val: impl TableInsert<T = T>, ) -> Result<TableRow<T>, T::Conflict>

Try inserting a value into the database.

Returns Ok with a reference to the new inserted value or an Err with conflict information. The type of conflict information depends on the number of unique constraints on the table:

• 0 unique constraints => Infallible
• 1 unique constraint => Expr reference to the conflicting table row.
• 2+ unique constraints => () no further information is provided.

let res = txn.insert(User {
    name: "Bob",
});
assert!(res.is_ok());
let res = txn.insert(User {
    name: "Bob",
});
assert!(res.is_err(), "there is a unique constraint on the name");

pub fn insert_ok<T: Table<Schema = S, Conflict = Infallible>>( &mut self, val: impl TableInsert<T = T>, ) -> TableRow<T>

This is a convenience function to make using Transaction::insert easier for tables without unique constraints.

The new row is added to the table and the row reference is returned.

pub fn find_or_insert<T: Table<Schema = S, Conflict = TableRow<T>>>( &mut self, val: impl TableInsert<T = T>, ) -> TableRow<T>

This is a convenience function to make using Transaction::insert easier for tables with exactly one unique constraints.

The new row is inserted and the reference to the row is returned OR an existing row is found which conflicts with the new row and a reference to the conflicting row is returned.

let bob = txn.insert(User {
    name: "Bob",
}).unwrap();
let bob2 = txn.find_or_insert(User {
    name: "Bob", // this will conflict with the existing row.
});
assert_eq!(bob, bob2);

pub fn update<T: Table<Schema = S>>( &mut self, row: impl IntoExpr<'static, S, Typ = T>, val: T::Update, ) -> Result<(), T::Conflict>

Try updating a row in the database to have new column values.

Updating can fail just like Transaction::insert because of unique constraint conflicts. This happens when the new values are in conflict with an existing different row.

When the update succeeds, this function returns Ok, when it fails it returns Err with one of three conflict types:

• 0 unique constraints => Infallible
• 1 unique constraint => Expr reference to the conflicting table row.
• 2+ unique constraints => () no further information is provided.

let bob = txn.insert(User {
    name: "Bob",
}).unwrap();
txn.update(bob, User {
    name: Update::set("New Bob"),
}).unwrap();

pub fn update_ok<T: Table<Schema = S>>( &mut self, row: impl IntoExpr<'static, S, Typ = T>, val: T::UpdateOk, )

This is a convenience function to use Transaction::update for updates that can not cause unique constraint violations.

This method can be used for all tables, it just does not allow modifying columns that are part of unique constraints.

pub fn downgrade(&'static mut self) -> &'static mut TransactionWeak<S>

Convert the Transaction into a TransactionWeak to allow deletions.