Struct rusqlite::Transaction
source · pub struct Transaction<'conn> { /* private fields */ }
Expand description
Represents a transaction on a database connection.
§Note
Transactions will roll back by default. Use commit
method to explicitly
commit the transaction, or use set_drop_behavior
to change what happens
when the transaction is dropped.
§Example
fn perform_queries(conn: &mut Connection) -> Result<()> {
let tx = conn.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()
}
Implementations§
source§impl Transaction<'_>
impl Transaction<'_>
sourcepub fn new(
conn: &mut Connection,
behavior: TransactionBehavior,
) -> Result<Transaction<'_>>
pub fn new( conn: &mut Connection, behavior: TransactionBehavior, ) -> Result<Transaction<'_>>
Begin a new transaction. Cannot be nested; see savepoint
for nested
transactions.
Even though we don’t mutate the connection, we take a &mut Connection
so as to prevent nested transactions on the same connection. For cases
where this is unacceptable, Transaction::new_unchecked
is available.
sourcepub fn new_unchecked(
conn: &Connection,
behavior: TransactionBehavior,
) -> Result<Transaction<'_>>
pub fn new_unchecked( conn: &Connection, behavior: TransactionBehavior, ) -> Result<Transaction<'_>>
Begin a new transaction, failing if a transaction is open.
If a transaction is already open, this will return an error. Where
possible, Transaction::new
should be preferred, as it provides a
compile-time guarantee that transactions are not nested.
sourcepub fn savepoint(&mut self) -> Result<Savepoint<'_>>
pub fn savepoint(&mut self) -> Result<Savepoint<'_>>
Starts a new savepoint, allowing nested transactions.
§Note
Just like outer level transactions, savepoint transactions rollback by default.
§Example
fn perform_queries(conn: &mut Connection) -> Result<()> {
let mut tx = conn.transaction()?;
{
let sp = tx.savepoint()?;
if perform_queries_part_1_succeeds(&sp) {
sp.commit()?;
}
// otherwise, sp will rollback
}
tx.commit()
}
sourcepub fn savepoint_with_name<T: Into<String>>(
&mut self,
name: T,
) -> Result<Savepoint<'_>>
pub fn savepoint_with_name<T: Into<String>>( &mut self, name: T, ) -> Result<Savepoint<'_>>
Create a new savepoint with a custom savepoint name. See savepoint()
.
sourcepub fn drop_behavior(&self) -> DropBehavior
pub fn drop_behavior(&self) -> DropBehavior
Get the current setting for what happens to the transaction when it is dropped.
sourcepub fn set_drop_behavior(&mut self, drop_behavior: DropBehavior)
pub fn set_drop_behavior(&mut self, drop_behavior: DropBehavior)
Configure the transaction to perform the specified action when it is dropped.
sourcepub fn commit(self) -> Result<()>
pub fn commit(self) -> Result<()>
A convenience method which consumes and commits a transaction.
Methods from Deref<Target = Connection>§
sourcepub fn busy_timeout(&self, timeout: Duration) -> Result<()>
pub fn busy_timeout(&self, timeout: Duration) -> Result<()>
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.
sourcepub fn busy_handler(&self, callback: Option<fn(_: i32) -> bool>) -> Result<()>
pub fn busy_handler(&self, callback: Option<fn(_: i32) -> bool>) -> Result<()>
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.
sourcepub fn prepare_cached(&self, sql: &str) -> Result<CachedStatement<'_>>
pub fn prepare_cached(&self, sql: &str) -> Result<CachedStatement<'_>>
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 (?1)")?;
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 (?1)")?;
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.
sourcepub fn set_prepared_statement_cache_capacity(&self, capacity: usize)
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.
sourcepub fn flush_prepared_statement_cache(&self)
pub fn flush_prepared_statement_cache(&self)
Remove/finalize all prepared statements currently in the cache.
sourcepub fn db_config(&self, config: DbConfig) -> Result<bool>
pub fn db_config(&self, config: DbConfig) -> Result<bool>
Returns the current value of a config
.
SQLITE_DBCONFIG_ENABLE_FKEY
: returnfalse
ortrue
to indicate whether FK enforcement is off or onSQLITE_DBCONFIG_ENABLE_TRIGGER
: returnfalse
ortrue
to indicate whether triggers are disabled or enabledSQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
: returnfalse
ortrue
to indicate whetherfts3_tokenizer
are disabled or enabledSQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
: returnfalse
to indicate checkpoints-on-close are not disabled ortrue
if they areSQLITE_DBCONFIG_ENABLE_QPSG
: returnfalse
ortrue
to indicate whether the QPSG is disabled or enabledSQLITE_DBCONFIG_TRIGGER_EQP
: returnfalse
to indicate output-for-trigger are not disabled ortrue
if it is
sourcepub fn set_db_config(&self, config: DbConfig, new_val: bool) -> Result<bool>
pub fn set_db_config(&self, config: DbConfig, new_val: bool) -> Result<bool>
Make configuration changes to a database connection
SQLITE_DBCONFIG_ENABLE_FKEY
:false
to disable FK enforcement,true
to enable FK enforcementSQLITE_DBCONFIG_ENABLE_TRIGGER
:false
to disable triggers,true
to enable triggersSQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
:false
to disablefts3_tokenizer()
,true
to enablefts3_tokenizer()
SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
:false
(the default) to enable checkpoints-on-close,true
to disable themSQLITE_DBCONFIG_ENABLE_QPSG
:false
to disable the QPSG,true
to enable QPSGSQLITE_DBCONFIG_TRIGGER_EQP
:false
to disable output for trigger programs,true
to enable it
sourcepub fn set_limit(&self, limit: Limit, new_val: i32) -> i32
pub fn set_limit(&self, limit: Limit, new_val: i32) -> i32
Changes the Limit
to new_val
, returning the prior
value of the limit.
sourcepub fn pragma_query_value<T, F>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
f: F,
) -> Result<T>
pub fn pragma_query_value<T, F>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, f: F, ) -> Result<T>
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;
sourcepub fn pragma_query<F>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
f: F,
) -> Result<()>
pub fn pragma_query<F>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, f: F, ) -> Result<()>
Query the current rows/values of pragma_name
.
Prefer PRAGMA function introduced in SQLite 3.20:
SELECT * FROM pragma_collation_list;
sourcepub fn pragma<F, V>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
pragma_value: V,
f: F,
) -> Result<()>
pub fn pragma<F, V>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, pragma_value: V, f: F, ) -> Result<()>
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(?1);
sourcepub fn pragma_update<V>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
pragma_value: V,
) -> Result<()>where
V: ToSql,
pub fn pragma_update<V>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
pragma_value: V,
) -> Result<()>where
V: ToSql,
Set a new value to pragma_name
.
Some pragmas will return the updated value which cannot be retrieved with this method.
sourcepub fn pragma_update_and_check<F, T, V>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
pragma_value: V,
f: F,
) -> Result<T>
pub fn pragma_update_and_check<F, T, V>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, pragma_value: V, f: F, ) -> Result<T>
Set a new value to pragma_name
and return the updated value.
Only few pragmas automatically return the updated value.
sourcepub fn unchecked_transaction(&self) -> Result<Transaction<'_>>
pub fn unchecked_transaction(&self) -> Result<Transaction<'_>>
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.
sourcepub fn transaction_state(
&self,
db_name: Option<DatabaseName<'_>>,
) -> Result<TransactionState>
pub fn transaction_state( &self, db_name: Option<DatabaseName<'_>>, ) -> Result<TransactionState>
Determine the transaction state of a database
sourcepub fn execute_batch(&self, sql: &str) -> Result<()>
pub fn execute_batch(&self, sql: &str) -> Result<()>
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.
sourcepub fn execute<P: Params>(&self, sql: &str, params: P) -> Result<usize>
pub fn execute<P: Params>(&self, sql: &str, params: P) -> Result<usize>
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 = ?1", [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.
sourcepub fn path(&self) -> Option<&str>
pub fn path(&self) -> Option<&str>
Returns the path to the database file, if one exists and is known.
Returns Some("")
for a temporary or in-memory database.
Note that in some cases PRAGMA database_list is likely to be more robust.
sourcepub fn last_insert_rowid(&self) -> i64
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.
sourcepub fn query_row<T, P, F>(&self, sql: &str, params: P, f: F) -> Result<T>
pub fn query_row<T, P, F>(&self, sql: &str, params: P, f: F) -> Result<T>
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.
sourcepub fn query_row_and_then<T, E, P, F>(
&self,
sql: &str,
params: P,
f: F,
) -> Result<T, E>
pub fn query_row_and_then<T, E, P, F>( &self, sql: &str, params: P, f: F, ) -> Result<T, E>
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.
sourcepub fn prepare(&self, sql: &str) -> Result<Statement<'_>>
pub fn prepare(&self, sql: &str) -> Result<Statement<'_>>
Prepare a SQL statement for execution.
§Example
fn insert_new_people(conn: &Connection) -> Result<()> {
let mut stmt = conn.prepare("INSERT INTO People (name) VALUES (?1)")?;
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.
sourcepub fn prepare_with_flags(
&self,
sql: &str,
flags: PrepFlags,
) -> Result<Statement<'_>>
pub fn prepare_with_flags( &self, sql: &str, flags: PrepFlags, ) -> Result<Statement<'_>>
Prepare a SQL statement for execution.
§Failure
Will return Err
if sql
cannot be converted to a C-compatible string
or if the underlying SQLite call fails.
sourcepub unsafe fn handle(&self) -> *mut sqlite3
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
.
sourcepub fn get_interrupt_handle(&self) -> InterruptHandle
pub fn get_interrupt_handle(&self) -> InterruptHandle
Get access to a handle that can be used to interrupt long running queries from another thread.
sourcepub fn changes(&self) -> u64
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.
sourcepub fn is_autocommit(&self) -> bool
pub fn is_autocommit(&self) -> bool
Test for auto-commit mode. Autocommit mode is on by default.
sourcepub fn cache_flush(&self) -> Result<()>
pub fn cache_flush(&self) -> Result<()>
Flush caches to disk mid-transaction
sourcepub fn is_readonly(&self, db_name: DatabaseName<'_>) -> Result<bool>
pub fn is_readonly(&self, db_name: DatabaseName<'_>) -> Result<bool>
Determine if a database is read-only