Struct rusqlite::CachedStatement

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

Cacheable statement.

Statement will return automatically to the cache by default. If you want the statement to be discarded, call discard() on it.

Methods

impl<'conn> CachedStatement<'conn>

fn discard(self)

Discard the statement, preventing it from being returned to its Connection's collection of cached statements.

Methods from Deref<Target=Statement<'conn>>

fn parameter_index(&self, name: &str) -> Result<Option<i32>>

Return the index of an SQL parameter given its name.

Failure

Will return Err if name is invalid. Will return Ok(None) if the name is valid but not a bound parameter of this statement.

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

Execute the prepared statement with named parameter(s). If any parameters that were in the prepared statement are not included in params, they will continue to use the most-recently bound value from a previous call to execute_named, or NULL if they have never been bound.

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

Example

fn insert(conn: &Connection) -> Result<i32> {
    let mut stmt = try!(conn.prepare("INSERT INTO test (name) VALUES (:name)"));
    stmt.execute_named(&[(":name", &"one")])
}

Failure

Will return Err if binding parameters fails, the executed statement returns rows (in which case query should be used instead), or the underling SQLite call fails.

fn query_named<'a>(&'a mut self, params: &[(&str, &ToSql)]) -> Result<Rows<'a>>

Execute the prepared statement with named parameter(s), returning a handle for the resulting rows. If any parameters that were in the prepared statement are not included in params, they will continue to use the most-recently bound value from a previous call to query_named, or NULL if they have never been bound.

Example

fn query(conn: &Connection) -> Result<()> {
    let mut stmt = try!(conn.prepare("SELECT * FROM test where name = :name"));
    let mut rows = try!(stmt.query_named(&[(":name", &"one")]));
    while let Some(row) = rows.next() {
        // ...
    }
    Ok(())
}

Failure

Will return Err if binding parameters fails.

fn query_map_named<'a, T, F>(&'a mut self,
                             params: &[(&str, &ToSql)],
                             f: F)
                             -> Result<MappedRows<'a, F>> where F: FnMut(&Row) -> T

Execute the prepared statement with named parameter(s), returning an iterator over the result of calling the mapping function over the query's rows. If any parameters that were in the prepared statement are not included in params, they will continue to use the most-recently bound value from a previous call to query_named, or NULL if they have never been bound.

Example

fn get_names(conn: &Connection) -> Result<Vec<String>> {
    let mut stmt = try!(conn.prepare("SELECT name FROM people WHERE id = :id"));
    let rows = try!(stmt.query_map_named(&[(":id", &"one")], |row| row.get(0)));

    let mut names = Vec::new();
    for name_result in rows {
        names.push(try!(name_result));
    }

    Ok(names)
}

Failure

Will return Err if binding parameters fails.

fn query_and_then_named<'a, T, E, F>(&'a mut self,
                                     params: &[(&str, &ToSql)],
                                     f: F)
                                     -> Result<AndThenRows<'a, F>> where E: From<Error>, F: FnMut(&Row) -> Result<T, E>

Execute the prepared statement with named parameter(s), returning an iterator over the result of calling the mapping function over the query's rows. If any parameters that were in the prepared statement are not included in params, they will continue to use the most-recently bound value from a previous call to query_named, or NULL if they have never been bound.

Example

struct Person { name: String };

fn name_to_person(name: String) -> Result<Person> {
    // ... check for valid name
    Ok(Person{ name: name })
}

fn get_names(conn: &Connection) -> Result<Vec<Person>> {
    let mut stmt = try!(conn.prepare("SELECT name FROM people WHERE id = :id"));
    let rows = try!(stmt.query_and_then_named(&[(":id", &"one")], |row| {
        name_to_person(row.get(0))
    }));

    let mut persons = Vec::new();
    for person_result in rows {
        persons.push(try!(person_result));
    }

    Ok(persons)
}

Failure

Will return Err if binding parameters fails.

fn insert(&mut self, params: &[&ToSql]) -> Result<i64>

Execute an INSERT and return the ROWID.

Note

This function is a convenience wrapper around execute() intended for queries that insert a single item. It is possible to misuse this function in a way that it cannot detect, such as by calling it on a statement which updates a single item rather than inserting one. Please don't do that.

Failure

Will return Err if no row is inserted or many rows are inserted.

fn exists(&mut self, params: &[&ToSql]) -> Result<bool>

Return true if a query in the SQL statement it executes returns one or more rows and false if the SQL returns an empty set.

fn query_row<T, F>(&mut self, 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.

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

Failure

Will return Err if the underlying SQLite call fails.

fn column_names(&self) -> Vec<&str>

Get all the column names in the result set of the prepared statement.

fn column_count(&self) -> i32

Return the number of columns in the result set returned by the prepared statement.

fn column_index(&self, name: &str) -> Result<i32>

Returns the column index in the result set for a given column name.

If there is no AS clause then the name of the column is unspecified and may change from one release of SQLite to the next.

Failure

Will return an Error::InvalidColumnName when there is no column with the specified name.

fn execute(&mut self, params: &[&ToSql]) -> Result<c_int>

Execute the prepared statement.

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

Example

fn update_rows(conn: &Connection) -> Result<()> {
    let mut stmt = try!(conn.prepare("UPDATE foo SET bar = 'baz' WHERE qux = ?"));

    try!(stmt.execute(&[&1i32]));
    try!(stmt.execute(&[&2i32]));

    Ok(())
}

Failure

Will return Err if binding parameters fails, the executed statement returns rows (in which case query should be used instead), or the underling SQLite call fails.

fn query<'a>(&'a mut self, params: &[&ToSql]) -> Result<Rows<'a>>

Execute the prepared statement, returning a handle to the resulting rows.

Due to lifetime restricts, the rows handle returned by query does not implement the Iterator trait. Consider using query_map or query_and_then instead, which do.

Example

fn get_names(conn: &Connection) -> Result<Vec<String>> {
    let mut stmt = try!(conn.prepare("SELECT name FROM people"));
    let mut rows = try!(stmt.query(&[]));

    let mut names = Vec::new();
    while let Some(result_row) = rows.next() {
        let row = try!(result_row);
        names.push(row.get(0));
    }

    Ok(names)
}

Failure

Will return Err if binding parameters fails.

fn query_map<'a, T, F>(&'a mut self,
                       params: &[&ToSql],
                       f: F)
                       -> Result<MappedRows<'a, F>> where F: FnMut(&Row) -> T

Executes the prepared statement and maps a function over the resulting rows, returning an iterator over the mapped function results.

Example

fn get_names(conn: &Connection) -> Result<Vec<String>> {
    let mut stmt = try!(conn.prepare("SELECT name FROM people"));
    let rows = try!(stmt.query_map(&[], |row| row.get(0)));

    let mut names = Vec::new();
    for name_result in rows {
        names.push(try!(name_result));
    }

    Ok(names)
}

Failure

Will return Err if binding parameters fails.

fn query_and_then<'a, T, E, F>(&'a mut self,
                               params: &[&ToSql],
                               f: F)
                               -> Result<AndThenRows<'a, F>> where E: From<Error>, F: FnMut(&Row) -> Result<T, E>

Executes the prepared statement and maps a function over the resulting rows, where the function returns a Result with Error type implementing std::convert::From<Error> (so errors can be unified).

Failure

Will return Err if binding parameters fails.

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

Consumes the statement.

Functionally equivalent to the Drop implementation, but allows callers to see any errors that occur.

Failure

Will return Err if the underlying SQLite call fails.

Trait Implementations

impl<'conn> Deref for CachedStatement<'conn>

type Target = Statement<'conn>

The resulting type after dereferencing

fn deref(&self) -> &Statement<'conn>

The method called to dereference a value

impl<'conn> DerefMut for CachedStatement<'conn>

fn deref_mut(&mut self) -> &mut Statement<'conn>

The method called to mutably dereference a value

impl<'conn> Drop for CachedStatement<'conn>

fn drop(&mut self)

A method called when the value goes out of scope.