Struct teil::SyncTransaction

impl<'a> SyncTransaction<'a>

pub fn new(transaction: Transaction<'a>) -> SyncTransaction<'a>

Creates an instance of the (SyncTransaction)SyncTransaction structure

pub fn commit(self) -> Result<(), Error>

Commits all the changes and consumes the transaction

use teil::{SyncConnection};
 
let mut connection = SyncConnection::new().unwrap();
let transaction = connection.transaction().unwrap();
 
// We use the transaction somehow
 
transaction.commit().unwrap();

pub fn rollback(self) -> Result<(), Error>

Performs a rollback to the changes and consumes the transaction

use teil::{SyncConnection};
 
let mut connection = SyncConnection::new().unwrap();
let transaction = connection.transaction().unwrap();
 
// We use the transaction somehow
 
transaction.rollback().unwrap();

pub fn retrieve<T: SyncTeil, A: Into<<T as SyncTeil>::Id>>(
&self,
id: A
) -> Result<Option<T>, Error>

Performs a retrieve operation using the transaction.

use teil::{SyncTeil, SyncConnection};

#[derive(SyncTeil)]
struct User {
    #[teil(primary_key)]
    name: String
}
 
let mut connection = SyncConnection::new().unwrap();
let transaction = connection.transaction().unwrap();
 
let user: User = match transaction.retrieve("some_name") {
    Ok(Some(v)) => v,
    Ok(None) => {
        println!("user with name some_name not found");
        return;
    },
    Err(e) => {
        println!("could not retrieve object from db, {}", e);
        return;
    }
};

pub fn save<T: SyncTeil>(
&self,
teil: &mut T
) -> Result<<T as SyncTeil>::Id, Error>

Performs a save operation using the transaction.

use teil::{SyncTeil, SyncConnection};

#[derive(SyncTeil)]
struct User {
    #[teil(primary_key)]
    name: String
}
 
let mut connection = SyncConnection::new().unwrap();
let transaction = connection.transaction().unwrap();
 
let mut user = User{name: "some_name".to_string()};
match transaction.save(&mut user) {
    Ok(_id) => {
        println!("saved user to the database!");
    },
    Err(e) => {
        println!("could not save object to db, {}", e);
    }
};

pub fn delete<T: SyncTeil, A: Into<<T as SyncTeil>::Id>>(
&self,
id: A
) -> Result<Option<T>, Error>

Performs a delete operation using the transaction.

use teil::{SyncTeil, SyncConnection};

#[derive(SyncTeil)]
struct User {
    #[teil(primary_key)]
    name: String
}
 
let mut connection = SyncConnection::new().unwrap();
let transaction = connection.transaction().unwrap();
 
// Using the turbofish...
match transaction.delete::<User, _>("some_name") {
    Ok(Some(_)) => (),
    Ok(None) => {
        println!("user with name some_name not found");
    },
    Err(e) => {
        println!("could not retrieve object from db, {}", e);
    }
};

pub fn update_all<T: SyncTeil>(&self, teil: &T) -> Result<bool, Error>

Performs a full update to an object using the transaction.

use teil::{SyncTeil, SyncConnection};

#[derive(SyncTeil)]
struct User {
    #[teil(primary_key)]
    name: String,
    amount: i32
}
 
let mut connection = SyncConnection::new().unwrap();
let transaction = connection.transaction().unwrap();
 
let mut user = User{name: "some_name".to_string(), amount: 10};
// Will update all non-primary keys (amount)
match transaction.update_all(&user) {
    Ok(_) => {
        println!("updated object in the database!");
    },
    Err(e) => {
        println!("could not save object to db, {}", e);
    }
};

pub fn execute_update<U: SyncUpdate>(&self, update: U) -> Result<bool, Error>

Performs a partial update to an object using the transaction.

use teil::{SyncTeil, SyncConnection};

#[derive(SyncTeil)]
struct User {
    #[teil(primary_key)]
    name: String,
    amount: i32,
    base_amount: i32
}
 
let mut connection = SyncConnection::new().unwrap();
let transaction = connection.transaction().unwrap();
 
let user_update = User::update("some_name").set_base_amount(100);
// Will update only the base_amount
match transaction.execute_update(user_update) {
    Ok(_) => {
        println!("updated user object in the database");
    },
    Err(e) => {
        println!("could not save object to db, {}", e);
    }
};

pub fn query_vec<T: SyncTeil>(
 &self,
 filters: Option<Vec<<T as SyncTeil>::Filter>>,
 sort: Option<Vec<<T as SyncTeil>::Sort>>,
 offset: Option<usize>,
 limit: Option<usize>
) -> Result<Vec<T>, Error>

Performs a query with optional parameters using the transaction.

This function is cumbersome to use, you should prefer execute_query instead.

use teil::{SyncTeil, SyncConnection};

#[derive(SyncTeil)]
struct User {
    #[teil(primary_key)]
    name: String
}
 
let mut connection = SyncConnection::new().unwrap();
let transaction = connection.transaction().unwrap();
 
// Gets all elements from the user table
match transaction.query_vec::<User>(None, None, None, None) {
    Ok(_vals) => {
        println!("retrieved objects from the database");
        // Do something with the objects...
    },
    Err(e) => {
        println!("could not save object to db, {}", e);
    }
};

pub fn execute_query<T: SyncTeil>(
&self,
teil_query: SyncTeilQuery<T>
) -> Result<Vec<T>, Error>

Executes a SyncTeilQuery object using the transaction

use teil::{SyncTeil, SyncConnection};

#[derive(SyncTeil)]
struct User {
    #[teil(primary_key)]
    name: String,
    amount: i32,
    base_amount: i32
}
 
let mut connection = SyncConnection::new().unwrap();
let transaction = connection.transaction().unwrap();
 
let user_query = User::query();
// We query all values from the database
match transaction.execute_query(user_query) {
    Ok(_elems) => {
        println!("got elements from the database");
        // Do something with the elements
    },
    Err(e) => {
        println!("could not save object to db, {}", e);
    }
};

pub fn count<T: SyncTeil>(
&self,
filters: Vec<<T as SyncTeil>::Filter>
) -> Result<i64, Error>

Counts the number of elements in the database with the given filters, using the transaction

use teil::{SyncTeil, SyncConnection};

#[derive(SyncTeil)]
struct User {
    #[teil(primary_key)]
    name: String
}
 
let mut connection = SyncConnection::new().unwrap();
let transaction = connection.transaction().unwrap();
 
// Counts all the elements
match transaction.count::<User>(vec![]) {
    Ok(num_elems) => {
        println!("there are {} elems!", num_elems);
    },
    Err(e) => {
        println!("could not get object count from the db, {}", e);
    }
};

pub fn save_iter<'b, T: SyncTeil, A: IntoIterator<Item = &'b mut T>>(
&self,
elements: A
) -> Result<(), Error>

Saves a group of elements to the database using the transaction

use teil::{SyncTeil, SyncConnection};

#[derive(SyncTeil)]
struct User {
    #[teil(primary_key)]
    name: String
}
 
let mut connection = SyncConnection::new().unwrap();
let transaction = connection.transaction().unwrap();
 
let mut elems = vec![User{name: "Foo".to_string()}, User{name: "Bar".to_string()}];
// Counts all the elements
match transaction.save_iter(&mut elems) {
    Ok(_) => {
        println!("saved all elements to the database");
    },
    Err(e) => {
        println!("could not save elements, {}", e);
    }
};

pub fn into_inner(self) -> Transaction<'a>

Returns the inner rusqlite transaction

use teil::SyncConnection;
 
let mut connection = SyncConnection::new().unwrap();
let transaction = connection.transaction().unwrap().into_inner();

// Use the pool transaction, for example...
transaction.execute("DELETE FROM some_table WHERE id = ?;", ["some_id"]).unwrap();

Methods from Deref<Target = Transaction<'a>>§

pub fn drop_behavior(&self) -> DropBehavior

Get the current setting for what happens to the transaction when it is dropped.

Methods from Deref<Target = Connection>§

pub fn busy_timeout(&self, timeout: Duration) -> Result<(), Error>

Set a busy handler that sleeps for a specified amount of time when a table is locked. The handler will sleep multiple times until at least “ms” milliseconds of sleeping have accumulated.

Calling this routine with an argument equal to zero turns off all busy handlers.

There can only be a single busy handler for a particular database connection at any given moment. If another busy handler was defined (using busy_handler) prior to calling this routine, that other busy handler is cleared.

Newly created connections currently have a default busy timeout of 5000ms, but this may be subject to change.

pub fn busy_handler(
&self,
callback: Option<fn(_: i32) -> bool>
) -> Result<(), Error>

Register a callback to handle SQLITE_BUSY errors.

If the busy callback is None, then SQLITE_BUSY is returned immediately upon encountering the lock. The argument to the busy handler callback is the number of times that the busy handler has been invoked previously for the same locking event. If the busy callback returns false, then no additional attempts are made to access the database and SQLITE_BUSY is returned to the application. If the callback returns true, then another attempt is made to access the database and the cycle repeats.

There can only be a single busy handler defined for each database connection. Setting a new busy handler clears any previously set handler. Note that calling busy_timeout() or evaluating PRAGMA busy_timeout=N will change the busy handler and thus clear any previously set busy handler.

Newly created connections default to a busy_timeout() handler with a timeout of 5000ms, although this is subject to change.

pub fn prepare_cached(&self, sql: &str) -> Result<CachedStatement<'_>, Error>

Prepare a SQL statement for execution, returning a previously prepared (but not currently in-use) statement if one is available. The returned statement will be cached for reuse by future calls to prepare_cached once it is dropped.

fn insert_new_people(conn: &Connection) -> Result<()> {
    {
        let mut stmt = conn.prepare_cached("INSERT INTO People (name) VALUES (?)")?;
        stmt.execute(["Joe Smith"])?;
    }
    {
        // This will return the same underlying SQLite statement handle without
        // having to prepare it again.
        let mut stmt = conn.prepare_cached("INSERT INTO People (name) VALUES (?)")?;
        stmt.execute(["Bob Jones"])?;
    }
    Ok(())
}

Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying SQLite call fails.

pub fn set_prepared_statement_cache_capacity(&self, capacity: usize)

Set the maximum number of cached prepared statements this connection will hold. By default, a connection will hold a relatively small number of cached statements. If you need more, or know that you will not use cached statements, you can set the capacity manually using this method.

pub fn flush_prepared_statement_cache(&self)

Remove/finalize all prepared statements currently in the cache.

pub fn db_config(&self, config: DbConfig) -> Result<bool, Error>

Returns the current value of a config.

SQLITE_DBCONFIG_ENABLE_FKEY: return false or true to indicate whether FK enforcement is off or on
SQLITE_DBCONFIG_ENABLE_TRIGGER: return false or true to indicate whether triggers are disabled or enabled
SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER: return false or true to indicate whether fts3_tokenizer are disabled or enabled
SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE: return false to indicate checkpoints-on-close are not disabled or true if they are
SQLITE_DBCONFIG_ENABLE_QPSG: return false or true to indicate whether the QPSG is disabled or enabled
SQLITE_DBCONFIG_TRIGGER_EQP: return false to indicate output-for-trigger are not disabled or true if it is

pub fn set_db_config(
 &self,
 config: DbConfig,
 new_val: bool
) -> Result<bool, Error>

Make configuration changes to a database connection

SQLITE_DBCONFIG_ENABLE_FKEY: false to disable FK enforcement, true to enable FK enforcement
SQLITE_DBCONFIG_ENABLE_TRIGGER: false to disable triggers, true to enable triggers
SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER: false to disable fts3_tokenizer(), true to enable fts3_tokenizer()
SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE: false (the default) to enable checkpoints-on-close, true to disable them
SQLITE_DBCONFIG_ENABLE_QPSG: false to disable the QPSG, true to enable QPSG
SQLITE_DBCONFIG_TRIGGER_EQP: false to disable output for trigger programs, true to enable it

pub fn pragma_query_value<T, F>(
 &self,
 schema_name: Option<DatabaseName<'_>>,
 pragma_name: &str,
 f: F
) -> Result<T, Error>where
 F: FnOnce(&Row<'_>) -> Result<T, Error>,

Query the current value of pragma_name.

Some pragmas will return multiple rows/values which cannot be retrieved with this method.

Prefer PRAGMA function introduced in SQLite 3.20: SELECT user_version FROM pragma_user_version;

pub fn pragma_query<F>(
 &self,
 schema_name: Option<DatabaseName<'_>>,
 pragma_name: &str,
 f: F
) -> Result<(), Error>where
 F: FnMut(&Row<'_>) -> Result<(), Error>,

Query the current rows/values of pragma_name.

Prefer PRAGMA function introduced in SQLite 3.20: SELECT * FROM pragma_collation_list;

pub fn pragma<F, V>(
 &self,
 schema_name: Option<DatabaseName<'_>>,
 pragma_name: &str,
 pragma_value: V,
 f: F
) -> Result<(), Error>where
 F: FnMut(&Row<'_>) -> Result<(), Error>,
 V: ToSql,

Query the current value(s) of pragma_name associated to pragma_value.

This method can be used with query-only pragmas which need an argument (e.g. table_info('one_tbl')) or pragmas which returns value(s) (e.g. integrity_check).

Prefer PRAGMA function introduced in SQLite 3.20: SELECT * FROM pragma_table_info(?);

pub fn pragma_update<V>(
 &self,
 schema_name: Option<DatabaseName<'_>>,
 pragma_name: &str,
 pragma_value: V
) -> Result<(), Error>where
 V: ToSql,

Set a new value to pragma_name.

Some pragmas will return the updated value which cannot be retrieved with this method.

pub fn pragma_update_and_check<F, T, V>(
 &self,
 schema_name: Option<DatabaseName<'_>>,
 pragma_name: &str,
 pragma_value: V,
 f: F
) -> Result<T, Error>where
 F: FnOnce(&Row<'_>) -> Result<T, Error>,
 V: ToSql,

Set a new value to pragma_name and return the updated value.

Only few pragmas automatically return the updated value.

pub fn unchecked_transaction(&self) -> Result<Transaction<'_>, Error>

Begin a new transaction with the default behavior (DEFERRED).

Attempt to open a nested transaction will result in a SQLite error. Connection::transaction prevents this at compile time by taking &mut self, but Connection::unchecked_transaction() may be used to defer the checking until runtime.

See Connection::transaction and Transaction::new_unchecked (which can be used if the default transaction behavior is undesirable).

Example

fn perform_queries(conn: Rc<Connection>) -> Result<()> {
    let tx = conn.unchecked_transaction()?;

    do_queries_part_1(&tx)?; // tx causes rollback if this fails
    do_queries_part_2(&tx)?; // tx causes rollback if this fails

    tx.commit()
}

Failure

Will return Err if the underlying SQLite call fails. The specific error returned if transactions are nested is currently unspecified.

pub fn execute_batch(&self, sql: &str) -> Result<(), Error>

Convenience method to run multiple SQL statements (that cannot take any parameters).

Example

fn create_tables(conn: &Connection) -> Result<()> {
    conn.execute_batch(
        "BEGIN;
         CREATE TABLE foo(x INTEGER);
         CREATE TABLE bar(y TEXT);
         COMMIT;",
    )
}

Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying SQLite call fails.

pub fn execute(&self, sql: &str, params: P) -> Result<usize, Error>where
P: Params,

Convenience method to prepare and execute a single SQL statement.

On success, returns the number of rows that were changed or inserted or deleted (via sqlite3_changes).

Example

With positional params

fn update_rows(conn: &Connection) {
    match conn.execute("UPDATE foo SET bar = 'baz' WHERE qux = ?", [1i32]) {
        Ok(updated) => println!("{} rows were updated", updated),
        Err(err) => println!("update failed: {}", err),
    }
}

With positional params of varying types

fn update_rows(conn: &Connection) {
    match conn.execute(
        "UPDATE foo SET bar = 'baz' WHERE qux = ?1 AND quux = ?2",
        params![1i32, 1.5f64],
    ) {
        Ok(updated) => println!("{} rows were updated", updated),
        Err(err) => println!("update failed: {}", err),
    }
}

With named params

fn insert(conn: &Connection) -> Result<usize> {
    conn.execute(
        "INSERT INTO test (name) VALUES (:name)",
        &[(":name", "one")],
    )
}

Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying SQLite call fails.

pub fn path(&self) -> Option<&Path>

Returns the path to the database file, if one exists and is known.

Note that in some cases PRAGMA database_list is likely to be more robust.

pub fn execute_named(
 &self,
 sql: &str,
 params: &[(&str, &dyn ToSql)]
) -> Result<usize, Error>

👎Deprecated: You can use execute with named params now.

Convenience method to prepare and execute a single SQL statement with named parameter(s).

On success, returns the number of rows that were changed or inserted or deleted (via sqlite3_changes).

Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying SQLite call fails.

pub fn last_insert_rowid(&self) -> i64

Get the SQLite rowid of the most recent successful INSERT.

Uses sqlite3_last_insert_rowid under the hood.

pub fn query_row<T, P, F>(&self, sql: &str, params: P, f: F) -> Result<T, Error>where
P: Params,
F: FnOnce(&Row<'_>) -> Result<T, Error>,

Convenience method to execute a query that is expected to return a single row.

Example

fn preferred_locale(conn: &Connection) -> Result<String> {
    conn.query_row(
        "SELECT value FROM preferences WHERE name='locale'",
        [],
        |row| row.get(0),
    )
}

If the query returns more than one row, all rows except the first are ignored.

Returns Err(QueryReturnedNoRows) if no results are returned. If the query truly is optional, you can call .optional() on the result of this to get a Result<Option<T>>.

Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying SQLite call fails.

pub fn query_row_named<T, F>(
 &self,
 sql: &str,
 params: &[(&str, &dyn ToSql)],
 f: F
) -> Result<T, Error>where
 F: FnOnce(&Row<'_>) -> Result<T, Error>,

👎Deprecated: You can use query_row with named params now.

Convenience method to execute a query with named parameter(s) that is expected to return a single row.

If the query returns more than one row, all rows except the first are ignored.

Returns Err(QueryReturnedNoRows) if no results are returned. If the query truly is optional, you can call .optional() on the result of this to get a Result<Option<T>>.

Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying SQLite call fails.

pub fn query_row_and_then<T, E, P, F>(
 &self,
 sql: &str,
 params: P,
 f: F
) -> Result<T, E>where
 P: Params,
 F: FnOnce(&Row<'_>) -> Result<T, E>,
 E: From<Error>,

Convenience method to execute a query that is expected to return a single row, and execute a mapping via f on that returned row with the possibility of failure. The Result type of f must implement std::convert::From<Error>.

Example

fn preferred_locale(conn: &Connection) -> Result<String> {
    conn.query_row_and_then(
        "SELECT value FROM preferences WHERE name='locale'",
        [],
        |row| row.get(0),
    )
}

If the query returns more than one row, all rows except the first are ignored.

Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying SQLite call fails.

pub fn prepare(&self, sql: &str) -> Result<Statement<'_>, Error>

Prepare a SQL statement for execution.

Example

fn insert_new_people(conn: &Connection) -> Result<()> {
    let mut stmt = conn.prepare("INSERT INTO People (name) VALUES (?)")?;
    stmt.execute(["Joe Smith"])?;
    stmt.execute(["Bob Jones"])?;
    Ok(())
}

Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying SQLite call fails.

pub unsafe fn handle(&self) -> *mut sqlite3

Get access to the underlying SQLite database connection handle.

Warning

You should not need to use this function. If you do need to, please open an issue on the rusqlite repository and describe your use case.

Safety

This function is unsafe because it gives you raw access to the SQLite connection, and what you do with it could impact the safety of this Connection.

pub fn get_interrupt_handle(&self) -> InterruptHandle

Get access to a handle that can be used to interrupt long running queries from another thread.

See https://www.sqlite.org/c3ref/changes.html

pub fn changes(&self) -> u64

Return the number of rows modified, inserted or deleted by the most recently completed INSERT, UPDATE or DELETE statement on the database connection.

pub fn is_autocommit(&self) -> bool

Test for auto-commit mode. Autocommit mode is on by default.

Trait Implementations§

impl<'a> Deref for SyncTransaction<'a>

type Target = Transaction<'a>

The resulting type after dereferencing.

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

Dereferences the value.

Auto Trait Implementations§

impl<'a> !UnwindSafe for SyncTransaction<'a>

Blanket Implementations§

impl<T> Any for Twhere
T: 'static + ?Sized,

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

impl<T> Borrow<T> for Twhere
T: ?Sized,

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for Twhere
T: ?Sized,

const: unstable · source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Instrument for T

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

impl<T, U> Into for Twhere
U: From<T>,

const: unstable · source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

impl<T> Same<T> for T

type Output = T

Should always be Self

impl<T, U> TryFrom for Twhere
U: Into<T>,

type Error = Infallible

The type returned in the event of a conversion error.

const: unstable · source§

fn try_from(value: U) -> Result<T, <T as TryFrom>::Error>

Performs the conversion.

impl<T, U> TryInto for Twhere
U: TryFrom<T>,

type Error = >::Error

The type returned in the event of a conversion error.

const: unstable · source§

fn try_into(self) -> Result<U, >::Error>

Performs the conversion.

impl<V, T> VZip<V> for Twhere
V: MultiLane<T>,

fn vzip(self) -> V

impl<T> WithSubscriber for T

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where
S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more