Struct rusqlite::SqliteConnection

pub struct SqliteConnection {
    // some fields omitted
}

A connection to a SQLite database.

Warning

Note that despite the fact that most SqliteConnection methods take an immutable reference to self, SqliteConnection is NOT threadsafe, and using it from multiple threads may result in runtime panics or data races. The SQLite connection handle has at least two pieces of internal state (the last insertion ID and the last error message) that rusqlite uses, but wrapping these APIs in a safe way from Rust would be too restrictive (for example, you would not be able to prepare multiple statements at the same time).

Methods

impl SqliteConnection

fn open<P: AsRef<Path>>(path: &P) -> SqliteResult<SqliteConnection>

Open a new connection to a SQLite database.

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

fn open_in_memory() -> SqliteResult<SqliteConnection>

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

fn open_with_flags<P: AsRef<Path>>(path: &P, flags: SqliteOpenFlags) -> SqliteResult<SqliteConnection>

Open a new connection to a SQLite database.

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

fn open_in_memory_with_flags(flags: SqliteOpenFlags) -> SqliteResult<SqliteConnection>

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.

fn transaction<'a>(&'a self) -> SqliteResult<SqliteTransaction<'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: &SqliteConnection) -> SqliteResult<()> {
    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()
}

fn transaction_with_behavior<'a>(&'a self, behavior: SqliteTransactionBehavior) -> SqliteResult<SqliteTransaction<'a>>

Begin a new transaction with a specified behavior.

See transaction.

fn execute_batch(&self, sql: &str) -> SqliteResult<()>

Convenience method to run multiple SQL statements (that cannot take any parameters).

Uses sqlite3_exec under the hood.

Example

fn create_tables(conn: &SqliteConnection) -> SqliteResult<()> {
    conn.execute_batch("BEGIN;
                        CREATE TABLE foo(x INTEGER);
                        CREATE TABLE bar(y TEXT);
                        COMMIT;")
}

fn execute(&self, sql: &str, params: &[&ToSql]) -> SqliteResult<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: &SqliteConnection) {
    match conn.execute("UPDATE foo SET bar = 'baz' WHERE qux = ?", &[&1i32]) {
        Ok(updated) => println!("{} rows were updated", updated),
        Err(err) => println!("update failed: {}", err),
    }
}

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) -> SqliteResult<T> where F: FnOnce(SqliteRow) -> T

Convenience method to execute a query that is expected to return a single row.

Example

fn preferred_locale(conn: &SqliteConnection) -> SqliteResult<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.

fn query_row_safe<T, F>(&self, sql: &str, params: &[&ToSql], f: F) -> SqliteResult<T> where F: FnOnce(SqliteRow) -> T

Convenience method to execute a query that is expected to return a single row.

Example

fn preferred_locale(conn: &SqliteConnection) -> SqliteResult<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) -> SqliteResult<SqliteStatement<'a>>

Prepare a SQL statement for execution.

Example

fn insert_new_people(conn: &SqliteConnection) -> SqliteResult<()> {
    let mut stmt = try!(conn.prepare("INSERT INTO People (name) VALUES (?)"));
    try!(stmt.execute(&[&"Joe Smith"]));
    try!(stmt.execute(&[&"Bob Jones"]));
    Ok(())
}

fn close(self) -> SqliteResult<()>

Close the SQLite connection.

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

Trait Implementations

impl Send for SqliteConnection

impl Debug for SqliteConnection

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