Struct rusqlite::Connection [−] [src]

pub struct Connection {
    // some fields omitted
}

A connection to a SQLite database.

Methods

impl Connection
[src]

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.

impl Connection
[src]

fn open<P: AsRef<Path>>(path: P) -> Result<Connection>

Open a new connection to a SQLite database.

Connection::open(path) is equivalent to Connection::open_with_flags(path, SQLITE_OPEN_READ_WRITE | SQLITE_OPEN_CREATE).

Failure

Will return Err if path cannot be converted to a C-compatible string or if the underlying SQLite open call fails.

fn open_in_memory() -> Result<Connection>

Open a new connection to an in-memory SQLite database.

Failure

Will return Err if the underlying SQLite open call fails.

fn open_with_flags<P: AsRef<Path>>(path: P, flags: OpenFlags) -> Result<Connection>

Open a new connection to a SQLite database.

Database Connection](http://www.sqlite.org/c3ref/open.html) for a description of valid flag combinations.

Failure

Will return Err if path cannot be converted to a C-compatible string or if the underlying SQLite open call fails.

fn open_in_memory_with_flags(flags: OpenFlags) -> Result<Connection>

Open a new connection to an in-memory SQLite database.

Database Connection](http://www.sqlite.org/c3ref/open.html) for a description of valid flag combinations.

Failure

Will return Err if the underlying SQLite open call fails.

fn transaction<'a>(&'a self) -> Result<Transaction<'a>>

Begin a new transaction with the default behavior (DEFERRED).

The transaction defaults to rolling back when it is dropped. If you want the transaction to commit, you must call commit or set_commit.

Example

fn perform_queries(conn: &Connection) -> Result<()> {
    let tx = try!(conn.transaction());

    try!(do_queries_part_1(conn)); // tx causes rollback if this fails
    try!(do_queries_part_2(conn)); // tx causes rollback if this fails

    tx.commit()
}

Failure

Will return Err if the underlying SQLite call fails.

fn transaction_with_behavior<'a>(&'a self, behavior: TransactionBehavior) -> Result<Transaction<'a>>

Begin a new transaction with a specified behavior.

See transaction.

Failure

Will return Err 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

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

Close the SQLite connection.

This is functionally equivalent to the Drop implementation for Connection except that it returns any error encountered to the caller.

Failure

Will return Err if the underlying SQLite call fails.

Trait Implementations

impl Send for Connection
[src]

impl Debug for Connection
[src]

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

Formats the value using the given formatter.