Struct rusqlite::Statement

source · 
pub struct Statement<'conn> { /* private fields */ }
Expand description

A prepared statement.

Implementations§

source§

impl Statement<'_>

source

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

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

If associated DB schema can be altered concurrently, you should make sure that current statement has already been stepped once before calling this method.

source

pub fn column_count(&self) -> usize

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

If associated DB schema can be altered concurrently, you should make sure that current statement has already been stepped once before calling this method.

source

pub fn column_name(&self, col: usize) -> Result<&str>

Returns the name assigned to a particular column in the result set returned by the prepared statement.

If associated DB schema can be altered concurrently, you should make sure that current statement has already been stepped once before calling this method.

§Failure

Returns an Error::InvalidColumnIndex if idx is outside the valid column range for this row.

§Panics

Panics when column name is not valid UTF-8.

source

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

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.

If associated DB schema can be altered concurrently, you should make sure that current statement has already been stepped once before calling this method.

§Failure

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

source§

impl Statement<'_>

source

pub fn execute<P: Params>(&mut self, params: P) -> Result<usize>

Execute the prepared statement.

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

§Example
§Use with positional parameters
fn update_rows(conn: &Connection) -> Result<()> {
    let mut stmt = conn.prepare("UPDATE foo SET bar = ?1 WHERE qux = ?2")?;
    // For a single parameter, or a parameter where all the values have
    // the same type, just passing an array is simplest.
    stmt.execute([2i32])?;
    // The `rusqlite::params!` macro is mostly useful when the parameters do not
    // all have the same type, or if there are more than 32 parameters
    // at once, but it can be used in other cases.
    stmt.execute(params![1i32])?;
    // However, it's not required, many cases are fine as:
    stmt.execute(&[&2i32])?;
    // Or even:
    stmt.execute([2i32])?;
    // If you really want to, this is an option as well.
    stmt.execute((2i32,))?;
    Ok(())
}
§Heterogeneous positional parameters
use rusqlite::{Connection, Result};
fn store_file(conn: &Connection, path: &str, data: &[u8]) -> Result<()> {
    let query = "INSERT OR REPLACE INTO files(path, hash, data) VALUES (?1, ?2, ?3)";
    let mut stmt = conn.prepare_cached(query)?;
    let hash: [u8; 32] = sha256(data);
    // The easiest way to pass positional parameters of have several
    // different types is by using a tuple.
    stmt.execute((path, hash, data))?;
    // Using the `params!` macro also works, and supports longer parameter lists:
    stmt.execute(rusqlite::params![path, hash, data])?;
    Ok(())
}
§Use with named parameters
fn insert(conn: &Connection) -> Result<()> {
    let mut stmt = conn.prepare("INSERT INTO test (key, value) VALUES (:key, :value)")?;
    // The `rusqlite::named_params!` macro (like `params!`) is useful for heterogeneous
    // sets of parameters (where all parameters are not the same type), or for queries
    // with many (more than 32) statically known parameters.
    stmt.execute(named_params! { ":key": "one", ":val": 2 })?;
    // However, named parameters can also be passed like:
    stmt.execute(&[(":key", "three"), (":val", "four")])?;
    // Or even: (note that a &T is required for the value type, currently)
    stmt.execute(&[(":key", &100), (":val", &200)])?;
    Ok(())
}
§Use without parameters
fn delete_all(conn: &Connection) -> Result<()> {
    let mut stmt = conn.prepare("DELETE FROM users")?;
    stmt.execute([])?;
    Ok(())
}
§Failure

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

source

pub fn insert<P: Params>(&mut self, params: P) -> 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.

source

pub fn query<P: Params>(&mut self, params: P) -> Result<Rows<'_>>

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

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

§Example
§Use without parameters
fn get_names(conn: &Connection) -> Result<Vec<String>> {
    let mut stmt = conn.prepare("SELECT name FROM people")?;
    let mut rows = stmt.query([])?;

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

    Ok(names)
}
§Use with positional parameters
fn query(conn: &Connection, name: &str) -> Result<()> {
    let mut stmt = conn.prepare("SELECT * FROM test where name = ?1")?;
    let mut rows = stmt.query(rusqlite::params![name])?;
    while let Some(row) = rows.next()? {
        // ...
    }
    Ok(())
}

Or, equivalently (but without the crate::params! macro).

fn query(conn: &Connection, name: &str) -> Result<()> {
    let mut stmt = conn.prepare("SELECT * FROM test where name = ?1")?;
    let mut rows = stmt.query([name])?;
    while let Some(row) = rows.next()? {
        // ...
    }
    Ok(())
}
§Use with named parameters
fn query(conn: &Connection) -> Result<()> {
    let mut stmt = conn.prepare("SELECT * FROM test where name = :name")?;
    let mut rows = stmt.query(&[(":name", "one")])?;
    while let Some(row) = rows.next()? {
        // ...
    }
    Ok(())
}

Note, the named_params! macro is provided for syntactic convenience, and so the above example could also be written as:

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

Will return Err if binding parameters fails.

source

pub fn query_map<T, P, F>( &mut self, params: P, f: F, ) -> Result<MappedRows<'_, F>>
where P: Params, F: FnMut(&Row<'_>) -> Result<T>,

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

f is used to transform the streaming iterator into a standard iterator.

This is equivalent to stmt.query(params)?.mapped(f).

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

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

    Ok(names)
}
§Use with named params
fn get_names(conn: &Connection) -> Result<Vec<String>> {
    let mut stmt = conn.prepare("SELECT name FROM people WHERE id = :id")?;
    let rows = stmt.query_map(&[(":id", &"one")], |row| row.get(0))?;

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

    Ok(names)
}
§Failure

Will return Err if binding parameters fails.

source

pub fn query_and_then<T, E, P, F>( &mut self, params: P, f: F, ) -> Result<AndThenRows<'_, F>>
where P: Params, 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).

This is equivalent to stmt.query(params)?.and_then(f).

§Example
§Use with named params
struct Person {
    name: String,
};

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

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

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

    Ok(persons)
}
§Use with positional params
fn get_names(conn: &Connection) -> Result<Vec<String>> {
    let mut stmt = conn.prepare("SELECT name FROM people WHERE id = ?1")?;
    let rows = stmt.query_and_then(["one"], |row| row.get::<_, String>(0))?;

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

    Ok(persons)
}
§Failure

Will return Err if binding parameters fails.

source

pub fn exists<P: Params>(&mut self, params: P) -> 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.

source

pub fn query_row<T, P, F>(&mut self, params: P, f: F) -> Result<T>
where P: Params, F: FnOnce(&Row<'_>) -> Result<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.

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>> (requires that the trait rusqlite::OptionalExtension is imported).

§Failure

Will return Err if the underlying SQLite call fails.

source

pub 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.

source

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

Return the (one-based) index of an SQL parameter given its name.

Note that the initial “:” or “$” or “@” or “?” used to specify the parameter is included as part of the name.

fn example(conn: &Connection) -> Result<()> {
    let stmt = conn.prepare("SELECT * FROM test WHERE name = :example")?;
    let index = stmt.parameter_index(":example")?;
    assert_eq!(index, Some(1));
    Ok(())
}
§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.

source

pub fn parameter_name(&self, index: usize) -> Option<&str>

Return the SQL parameter name given its (one-based) index (the inverse of Statement::parameter_index).

fn example(conn: &Connection) -> Result<()> {
    let stmt = conn.prepare("SELECT * FROM test WHERE name = :example")?;
    let index = stmt.parameter_name(1);
    assert_eq!(index, Some(":example"));
    Ok(())
}
§Failure

Will return None if the column index is out of bounds or if the parameter is positional.

§Panics

Panics when parameter name is not valid UTF-8.

source

pub fn parameter_count(&self) -> usize

Return the number of parameters that can be bound to this statement.

source

pub fn raw_bind_parameter<T: ToSql>( &mut self, one_based_col_index: usize, param: T, ) -> Result<()>

Low level API to directly bind a parameter to a given index.

Note that the index is one-based, that is, the first parameter index is 1 and not 0. This is consistent with the SQLite API and the values given to parameters bound as ?NNN.

The valid values for one_based_col_index begin at 1, and end at Statement::parameter_count, inclusive.

§Caveats

This should not generally be used, but is available for special cases such as:

  • binding parameters where a gap exists.
  • binding named and positional parameters in the same query.
  • separating parameter binding from query execution.

In general, statements that have had any parameters bound this way should have all parameters bound this way, and be queried or executed by Statement::raw_query or Statement::raw_execute, other usage is unsupported and will likely, probably in surprising ways.

That is: Do not mix the “raw” statement functions with the rest of the API, or the results may be surprising, and may even change in future versions without comment.

§Example
fn query(conn: &Connection) -> Result<()> {
    let mut stmt = conn.prepare("SELECT * FROM test WHERE name = :name AND value > ?2")?;
    let name_index = stmt.parameter_index(":name")?.expect("No such parameter");
    stmt.raw_bind_parameter(name_index, "foo")?;
    stmt.raw_bind_parameter(2, 100)?;
    let mut rows = stmt.raw_query();
    while let Some(row) = rows.next()? {
        // ...
    }
    Ok(())
}
source

pub fn raw_execute(&mut self) -> Result<usize>

Low level API to execute a statement given that all parameters were bound explicitly with the Statement::raw_bind_parameter API.

§Caveats

Any unbound parameters will have NULL as their value.

This should not generally be used outside of special cases, and functions in the Statement::execute family should be preferred.

§Failure

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

source

pub fn raw_query(&mut self) -> Rows<'_>

Low level API to get Rows for this query given that all parameters were bound explicitly with the Statement::raw_bind_parameter API.

§Caveats

Any unbound parameters will have NULL as their value.

This should not generally be used outside of special cases, and functions in the Statement::query family should be preferred.

Note that if the SQL does not return results, Statement::raw_execute should be used instead.

source

pub fn expanded_sql(&self) -> Option<String>

Returns a string containing the SQL text of prepared statement with bound parameters expanded.

source

pub fn get_status(&self, status: StatementStatus) -> i32

Get the value for one of the status counters for this statement.

source

pub fn reset_status(&self, status: StatementStatus) -> i32

Reset the value of one of the status counters for this statement, returning the value it had before resetting.

source

pub fn is_explain(&self) -> i32

Returns 1 if the prepared statement is an EXPLAIN statement, or 2 if the statement is an EXPLAIN QUERY PLAN, or 0 if it is an ordinary statement or a NULL pointer.

source

pub fn readonly(&self) -> bool

Returns true if the statement is read only.

source

pub fn clear_bindings(&mut self)

Reset all bindings

Trait Implementations§

source§

impl<'stmt> AsRef<Statement<'stmt>> for Row<'stmt>

source§

fn as_ref(&self) -> &Statement<'stmt>

Converts this type into a shared reference of the (usually inferred) input type.
source§

impl Debug for Statement<'_>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Drop for Statement<'_>

source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

§

impl<'conn> !Freeze for Statement<'conn>

§

impl<'conn> !RefUnwindSafe for Statement<'conn>

§

impl<'conn> !Send for Statement<'conn>

§

impl<'conn> !Sync for Statement<'conn>

§

impl<'conn> Unpin for Statement<'conn>

§

impl<'conn> !UnwindSafe for Statement<'conn>

Blanket Implementations§

source§

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

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

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

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

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

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

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

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.

source§

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

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

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

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.