Struct TransactionMut

pub struct TransactionMut<'t, S> { /* private fields */ }

Same as Transaction, but allows inserting new rows.

TransactionMut always uses the latest version of the database, with the effects of all previous TransactionMuts applied.

To make mutations to the database permanent you need to use TransactionMut::commit. This is to make sure that if a function panics while holding a mutable transaction, it will roll back those changes.

Implementations

impl<'t, S: 'static> TransactionMut<'t, S>

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

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<'t> = Infallible>>( &mut self, val: impl TableInsert<'t, T = T>, ) -> TableRow<'t, T>

This is a convenience function to make using TransactionMut::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<'t> = TableRow<'t, T>>>( &mut self, val: impl TableInsert<'t, T = T>, ) -> TableRow<'t, T>

This is a convenience function to make using TransactionMut::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<'t, S, Typ = T>, val: T::Update<'t>, ) -> Result<(), T::Conflict<'t>>

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

Updating can fail just like TransactionMut::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<'t, S, Typ = T>, val: T::UpdateOk<'t>, )

This is a convenience function to use TransactionMut::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 commit(self)

Make the changes made in this TransactionMut permanent.

If the TransactionMut is dropped without calling this function, then the changes are rolled back.

pub fn downgrade(self) -> TransactionWeak<'t, S>

Convert the TransactionMut into a TransactionWeak to allow deletions.

Methods from Deref<Target = Transaction<'t, S>>

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

where F: for<'inner> FnOnce(&mut Query<'t, '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<'e, O>(&self, val: impl IntoSelect<'t, 't, 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.

Trait Implementations

impl<'t, S> Deref for TransactionMut<'t, S>

type Target = Transaction<'t, S>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.