Struct rusqlite::Savepoint

pub struct Savepoint<'conn> { /* fields omitted */ }

Represents a savepoint on a database connection.

Note

Savepoints will roll back by default. Use commit method to explicitly commit the savepoint, or use set_drop_behavior to change what happens when the savepoint is dropped.

Example

fn perform_queries(conn: &mut Connection) -> Result<()> {
    let sp = try!(conn.savepoint());

    try!(do_queries_part_1(&sp)); // sp causes rollback if this fails
    try!(do_queries_part_2(&sp)); // sp causes rollback if this fails

    sp.commit()
}

Methods

impl<'conn> Savepoint<'conn>

fn new(conn: &mut Connection) -> Result<Savepoint>

Begin a new savepoint. Can be nested.

fn with_name<T: Into<String>>(conn: &mut Connection,
                              name: T)
                              -> Result<Savepoint>

Begin a new savepoint with a user-provided savepoint name.

fn savepoint(&mut self) -> Result<Savepoint>

Begin a nested savepoint.

fn savepoint_with_name<T: Into<String>>(&mut self, name: T) -> Result<Savepoint>

Begin a nested savepoint with a user-provided savepoint name.

fn drop_behavior(&self) -> DropBehavior

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

fn set_drop_behavior(&mut self, drop_behavior: DropBehavior)

Configure the savepoint to perform the specified action when it is dropped.

fn commit(self) -> Result<()>

A convenience method which consumes and commits a savepoint.

fn rollback(&mut self) -> Result<()>

A convenience method which rolls back a savepoint.

Note

Unlike Transactions, savepoints remain active after they have been rolled back, and can be rolled back again or committed.

fn finish(self) -> Result<()>

Consumes the savepoint, 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>>

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)

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)

fn execute_named(&self, sql: &str, params: &[(&str, &ToSql)]) -> Result<c_int>

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 query_row_named<T, F>(&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 execute_batch(&self, sql: &str) -> Result<()>

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>

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 last_insert_rowid(&self) -> i64

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

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_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>

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

Deprecated since 0.1.0

: 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>>

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)>

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.

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. 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 Savepoint<'conn>

type Target = Connection

The resulting type after dereferencing

fn deref(&self) -> &Connection

The method called to dereference a value

impl<'conn> Drop for Savepoint<'conn>

fn drop(&mut self)

A method called when the value goes out of scope.