Struct rusqlite::Transaction
[−]
[src]
pub struct Transaction<'conn> { /* fields omitted */ }
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 = try!(conn.transaction()); try!(do_queries_part_1(&tx)); // tx causes rollback if this fails try!(do_queries_part_2(&tx)); // tx causes rollback if this fails tx.commit() }
Methods
impl<'conn> Transaction<'conn>
[src]
fn new(
conn: &mut Connection,
behavior: TransactionBehavior
) -> Result<Transaction>
[src]
conn: &mut Connection,
behavior: TransactionBehavior
) -> Result<Transaction>
Begin a new transaction. Cannot be nested; see savepoint
for nested transactions.
fn savepoint(&mut self) -> Result<Savepoint>
[src]
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 = try!(conn.transaction()); { let sp = try!(tx.savepoint()); if perform_queries_part_1_succeeds(&sp) { try!(sp.commit()); } // otherwise, sp will rollback } tx.commit() }
fn savepoint_with_name<T: Into<String>>(&mut self, name: T) -> Result<Savepoint>
[src]
Create a new savepoint with a custom savepoint name. See savepoint()
.
fn drop_behavior(&self) -> DropBehavior
[src]
Get the current setting for what happens to the transaction when it is dropped.
fn set_drop_behavior(&mut self, drop_behavior: DropBehavior)
[src]
Configure the transaction to perform the specified action when it is dropped.
fn commit(self) -> Result<()>
[src]
A convenience method which consumes and commits a transaction.
fn rollback(self) -> Result<()>
[src]
A convenience method which consumes and rolls back a transaction.
fn finish(self) -> Result<()>
[src]
Consumes the transaction, committing or rolling back according to the current setting
(see drop_behavior
).
Functionally equivalent to the Drop
implementation, but allows callers to see any
errors that occur.
Methods from Deref<Target = Connection>
fn prepare_cached<'a>(&'a self, sql: &str) -> Result<CachedStatement<'a>>
[src]
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 = try!(conn.prepare_cached("INSERT INTO People (name) VALUES (?)")); try!(stmt.execute(&[&"Joe Smith"])); } { // This will return the same underlying SQLite statement handle without // having to prepare it again. let mut stmt = try!(conn.prepare_cached("INSERT INTO People (name) VALUES (?)")); try!(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.
fn set_prepared_statement_cache_capacity(&self, capacity: usize)
[src]
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.
fn flush_prepared_statement_cache(&self)
[src]
fn backup<P: AsRef<Path>>(
&self,
name: DatabaseName,
dst_path: P,
progress: Option<fn(_: Progress)>
) -> Result<()>
[src]
&self,
name: DatabaseName,
dst_path: P,
progress: Option<fn(_: Progress)>
) -> Result<()>
Back up the name
database to the given destination path.
If progress
is not None
, it will be called periodically
until the backup completes.
For more fine-grained control over the backup process (e.g.,
to sleep periodically during the backup or to back up to an
already-open database connection), see the backup
module.
Failure
Will return Err
if the destination path cannot be opened
or if the backup fails.
fn create_scalar_function<F, T>(
&self,
fn_name: &str,
n_arg: c_int,
deterministic: bool,
x_func: F
) -> Result<()> where
F: FnMut(&Context) -> Result<T>,
T: ToSql,
[src]
&self,
fn_name: &str,
n_arg: c_int,
deterministic: bool,
x_func: F
) -> Result<()> where
F: FnMut(&Context) -> Result<T>,
T: ToSql,
Attach a user-defined scalar function to this database connection.
fn_name
is the name the function will be accessible from SQL.
n_arg
is the number of arguments to the function. Use -1
for a variable
number. If the function always returns the same value given the same
input, deterministic
should be true
.
The function will remain available until the connection is closed or
until it is explicitly removed via remove_function
.
Example
fn scalar_function_example(db: Connection) -> Result<()> { try!(db.create_scalar_function("halve", 1, true, |ctx| { let value = try!(ctx.get::<f64>(0)); Ok(value / 2f64) })); let six_halved: f64 = try!(db.query_row("SELECT halve(6)", &[], |r| r.get(0))); assert_eq!(six_halved, 3f64); Ok(()) }
Failure
Will return Err if the function could not be attached to the connection.
fn create_aggregate_function<A, D, T>(
&self,
fn_name: &str,
n_arg: c_int,
deterministic: bool,
aggr: D
) -> Result<()> where
D: Aggregate<A, T>,
T: ToSql,
[src]
&self,
fn_name: &str,
n_arg: c_int,
deterministic: bool,
aggr: D
) -> Result<()> where
D: Aggregate<A, T>,
T: ToSql,
Attach a user-defined aggregate function to this database connection.
Failure
Will return Err if the function could not be attached to the connection.
fn remove_function(&self, fn_name: &str, n_arg: c_int) -> Result<()>
[src]
Removes a user-defined function from this database connection.
fn_name
and n_arg
should match the name and number of arguments
given to create_scalar_function
or create_aggregate_function
.
Failure
Will return Err if the function could not be removed.
fn blob_open<'a>(
&'a self,
db: DatabaseName,
table: &str,
column: &str,
row: i64,
read_only: bool
) -> Result<Blob<'a>>
[src]
&'a self,
db: DatabaseName,
table: &str,
column: &str,
row: i64,
read_only: bool
) -> Result<Blob<'a>>
Open a handle to the BLOB located in row
, column
, table
in database db
.
Failure
Will return Err
if db
/table
/column
cannot be converted to a C-compatible string
or if the underlying SQLite BLOB open call fails.
fn limit(&self, limit: Limit) -> i32
[src]
Returns the current value of a limit.
fn set_limit(&self, limit: Limit, new_val: i32) -> i32
[src]
Changes the limit to new_val
, returning the prior value of the limit.
fn execute_batch(&self, sql: &str) -> Result<()>
[src]
Convenience method to run multiple SQL statements (that cannot take any parameters).
Uses sqlite3_exec under the hood.
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.
fn execute(&self, sql: &str, params: &[&ToSql]) -> Result<c_int>
[src]
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
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), } }
Failure
Will return Err
if sql
cannot be converted to a C-compatible string or if the
underlying SQLite call fails.
fn execute_named(&self, sql: &str, params: &[(&str, &ToSql)]) -> Result<c_int>
[src]
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
).
Example
fn insert(conn: &Connection) -> Result<i32> { conn.execute_named("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.
fn last_insert_rowid(&self) -> i64
[src]
Get the SQLite rowid of the most recent successful INSERT.
Uses sqlite3_last_insert_rowid under the hood.
fn query_row<T, F>(&self, sql: &str, params: &[&ToSql], f: F) -> Result<T> where
F: FnOnce(&Row) -> T,
[src]
F: FnOnce(&Row) -> 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.
Failure
Will return Err
if sql
cannot be converted to a C-compatible string or if the
underlying SQLite call fails.
fn query_row_named<T, F>(
&self,
sql: &str,
params: &[(&str, &ToSql)],
f: F
) -> Result<T> where
F: FnOnce(&Row) -> T,
[src]
&self,
sql: &str,
params: &[(&str, &ToSql)],
f: F
) -> Result<T> where
F: FnOnce(&Row) -> T,
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.
Failure
Will return Err
if sql
cannot be converted to a C-compatible string or if the
underlying SQLite call fails.
fn query_row_and_then<T, E, F>(
&self,
sql: &str,
params: &[&ToSql],
f: F
) -> Result<T, E> where
F: FnOnce(&Row) -> Result<T, E>,
E: From<Error>,
[src]
&self,
sql: &str,
params: &[&ToSql],
f: F
) -> Result<T, E> where
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_checked(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.
fn query_row_safe<T, F>(&self, sql: &str, params: &[&ToSql], f: F) -> Result<T> where
F: FnOnce(&Row) -> T,
[src]
F: FnOnce(&Row) -> T,
: Use query_row instead
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_safe("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.
Deprecated
This method should be considered deprecated. Use query_row
instead, which now
does exactly the same thing.
fn prepare<'a>(&'a self, sql: &str) -> Result<Statement<'a>>
[src]
Prepare a SQL statement for execution.
Example
fn insert_new_people(conn: &Connection) -> Result<()> { let mut stmt = try!(conn.prepare("INSERT INTO People (name) VALUES (?)")); try!(stmt.execute(&[&"Joe Smith"])); try!(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.
fn close(self) -> Result<(), (Connection, Error)>
[src]
Close the SQLite connection.
This is functionally equivalent to the Drop
implementation for Connection
except
that on failure, it returns an error and the connection itself (presumably so closing
can be attempted again).
Failure
Will return Err
if the underlying SQLite call fails.
fn load_extension_enable(&self) -> Result<()>
[src]
Enable loading of SQLite extensions. Strongly consider using LoadExtensionGuard
instead of this function.
Example
fn load_my_extension(conn: &Connection) -> Result<()> { try!(conn.load_extension_enable()); try!(conn.load_extension(Path::new("my_sqlite_extension"), None)); conn.load_extension_disable() }
Failure
Will return Err
if the underlying SQLite call fails.
fn load_extension_disable(&self) -> Result<()>
[src]
Disable loading of SQLite extensions.
See load_extension_enable
for an example.
Failure
Will return Err
if the underlying SQLite call fails.
fn load_extension<P: AsRef<Path>>(
&self,
dylib_path: P,
entry_point: Option<&str>
) -> Result<()>
[src]
&self,
dylib_path: P,
entry_point: Option<&str>
) -> Result<()>
Load the SQLite extension at dylib_path
. dylib_path
is passed through to
sqlite3_load_extension
, which may attempt OS-specific modifications if the file
cannot be loaded directly.
If entry_point
is None
, SQLite will attempt to find the entry point. If it is not
None
, the entry point will be passed through to sqlite3_load_extension
.
Example
fn load_my_extension(conn: &Connection) -> Result<()> { let _guard = try!(LoadExtensionGuard::new(conn)); conn.load_extension("my_sqlite_extension", None) }
Failure
Will return Err
if the underlying SQLite call fails.
unsafe fn handle(&self) -> *mut sqlite3
[src]
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. 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
.
Trait Implementations
impl<'conn> Deref for Transaction<'conn>
[src]
type Target = Connection
The resulting type after dereferencing.
fn deref(&self) -> &Connection
[src]
Dereferences the value.