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<'t, R>(&'t self, f: impl FnOnce(&mut Query<'t, '_, S>) -> R) -> 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.

pub fn lazy<'t, T: OptTable<Schema = S>>( &'t self, val: impl IntoExpr<'static, S, Typ = T>, ) -> T::Lazy<'t>

Retrieve a crate::Lazy value from the database.

This is very similar to Self::query_one, except that it retrieves crate::Lazy instead of TableRow. As such it only works with table valued rust_query::Expr.

let cat = txn.insert_ok(Author {
    name: "Cat".to_owned()
});
let blog_post = txn.insert_ok(Page {
    content: "Hello world!".to_owned(),
    title: "Hi".to_owned(),
    author: cat,
});
let lazy_post = txn.lazy(blog_post);

println!("{}:", lazy_post.title);
println!("{}", lazy_post.content);
println!("written by: {}", lazy_post.author.name);

pub fn lazy_iter<'t, T: Table<Schema = S>>( &'t self, val: impl IntoJoinable<'static, S, Typ = TableRow<T>>, ) -> LazyIter<'t, T>

This retrieves an iterator of crate::Lazy values.

Refer to Rows::join for the kind of the parameter that is supported here. Refer to Transaction::lazy for the single row version.

pub fn mutable<'t, T: OptTable<Schema = S>>( &'t mut self, val: impl IntoExpr<'static, S, Typ = T>, ) -> T::Mutable<'t>

Retrieves a Mutable row from the database.

The Transaction is borrowed mutably until the Mutable is dropped. It is recommended to keep the lifetime of Mutable short, to prevent borrow checker errors. See below for some good examples of how to use Transaction::mutable.

if let Some(mut player) = txn.mutable(Player.number(1)) {
    player.score += 100;
}

let floris = txn.query_one(Player.name("Floris")).unwrap();
txn.mutable(floris).score += 50;

pub fn mutable_vec<'t, T: Table<Schema = S>>( &'t mut self, val: impl IntoJoinable<'static, S, Typ = TableRow<T>>, ) -> Vec<Mutable<'t, T>>

Retrieve multiple Mutable rows from the database.

Refer to Rows::join for the kind of the parameter that is supported here. This may be useful when you need mutable access to multiple rows (potentially at the same time).

for mut user in txn.mutable_vec(User) {
    user.age += 1;
}

impl<S: 'static> Transaction<S>

pub fn insert<T: Table<Schema = S>>( &mut self, val: 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 => TableRow reference to the conflicting table row.
• 2+ unique constraints => crate::Conflict.

let res = txn.insert(User {
    name: "Bob".to_owned(),
});
assert!(res.is_ok());
let res = txn.insert(User {
    name: "Bob".to_owned(),
});
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: 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: 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".to_owned(),
}).unwrap();
let bob2 = txn.find_or_insert(User {
    name: "Bob".to_owned(), // this will conflict with the existing row.
});
assert_eq!(bob, bob2);

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

Convert the Transaction into a TransactionWeak to allow deletions.