Struct rusqlite::Connection

pub struct Connection { /* fields omitted */ }

A connection to a SQLite database.

Methods

impl Connection

fn transaction(&mut self) -> Result<Transaction>

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_drop_behavior(DropBehavior::Commit).

Example

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

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

    tx.commit()
}

Failure

Will return Err if the underlying SQLite call fails.

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

Begin a new transaction with a specified behavior.

See transaction.

Failure

Will return Err if the underlying SQLite call fails.

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

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

The savepoint defaults to rolling back when it is dropped. If you want the savepoint to commit, you must call commit or set_drop_behavior(DropBehavior::Commit).

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

Failure

Will return Err if the underlying SQLite call fails.

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

Begin a new savepoint with a specified name.

See savepoint.

Failure

Will return Err if the underlying SQLite call fails.

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

impl Connection

fn trace(&mut self, trace_fn: Option<fn(_: &str)>)

Register or clear a callback function that can be used for tracing the execution of SQL statements.

Prepared statement placeholders are replaced/logged with their assigned values. There can only be a single tracer defined for each database connection. Setting a new tracer clears the old one.

fn profile(&mut self, profile_fn: Option<fn(_: &str, _: Duration)>)

Register or clear a callback function that can be used for profiling the execution of SQL statements.

There can only be a single profiler defined for each database connection. Setting a new profiler clears the old one.

impl Connection

fn backup<P: AsRef<Path>>(
    &self,
    name: DatabaseName,
    dst_path: P,
    progress: Option<fn(_: Progress)>
) -> Result<()>

Back up the name database to the given destination path. If progress is not None, it will be called periodically until the backup completes.

For more fine-grained control over the backup process (e.g., to sleep periodically during the backup or to back up to an already-open database connection), see the backup module.

Failure

Will return Err if the destination path cannot be opened or if the backup fails.

fn restore<P: AsRef<Path>>(
    &mut self,
    name: DatabaseName,
    src_path: P,
    progress: Option<fn(_: Progress)>
) -> Result<()>

Restore the given source path into the name database. If progress is not None, it will be called periodically until the restore completes.

For more fine-grained control over the restore process (e.g., to sleep periodically during the restore or to restore from an already-open database connection), see the backup module.

Failure

Will return Err if the destination path cannot be opened or if the restore fails.

impl Connection

fn create_scalar_function<F, T>(
    &self,
    fn_name: &str,
    n_arg: c_int,
    deterministic: bool,
    x_func: F
) -> Result<()> where
    F: FnMut(&Context) -> Result<T>,
    T: ToSql, 

Attach a user-defined scalar function to this database connection.

fn_name is the name the function will be accessible from SQL. n_arg is the number of arguments to the function. Use -1 for a variable number. If the function always returns the same value given the same input, deterministic should be true.

The function will remain available until the connection is closed or until it is explicitly removed via remove_function.

Example

fn scalar_function_example(db: Connection) -> Result<()> {
    try!(db.create_scalar_function("halve", 1, true, |ctx| {
        let value = try!(ctx.get::<f64>(0));
        Ok(value / 2f64)
    }));

    let six_halved: f64 = try!(db.query_row("SELECT halve(6)", &[], |r| r.get(0)));
    assert_eq!(six_halved, 3f64);
    Ok(())
}

Failure

Will return Err if the function could not be attached to the connection.

fn create_aggregate_function<A, D, T>(
    &self,
    fn_name: &str,
    n_arg: c_int,
    deterministic: bool,
    aggr: D
) -> Result<()> where
    D: Aggregate<A, T>,
    T: ToSql, 

Attach a user-defined aggregate function to this database connection.

Failure

Will return Err if the function could not be attached to the connection.

fn remove_function(&self, fn_name: &str, n_arg: c_int) -> Result<()>

Removes a user-defined function from this database connection.

fn_name and n_arg should match the name and number of arguments given to create_scalar_function or create_aggregate_function.

Failure

Will return Err if the function could not be removed.

impl Connection

fn blob_open<'a>(
    &'a self,
    db: DatabaseName,
    table: &str,
    column: &str,
    row: i64,
    read_only: bool
) -> Result<Blob<'a>>

Open a handle to the BLOB located in row, column, table in database db.

Failure

Will return Err if db/table/column cannot be converted to a C-compatible string or if the underlying SQLite BLOB open call fails.

impl Connection

fn limit(&self, limit: Limit) -> i32

Returns the current value of a limit.

fn set_limit(&self, limit: Limit, new_val: i32) -> i32

Changes the limit to new_val, returning the prior value of the limit.

impl Connection

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 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 for a description of valid flag combinations.

Failure

Will return Err if the underlying SQLite open 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 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 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_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 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.

fn load_extension_enable(&self) -> Result<()>

Enable loading of SQLite extensions. Strongly consider using LoadExtensionGuard instead of this function.

Example

fn load_my_extension(conn: &Connection) -> Result<()> {
    try!(conn.load_extension_enable());
    try!(conn.load_extension(Path::new("my_sqlite_extension"), None));
    conn.load_extension_disable()
}

Failure

Will return Err if the underlying SQLite call fails.

fn load_extension_disable(&self) -> Result<()>

Disable loading of SQLite extensions.

See load_extension_enable for an example.

Failure

Will return Err if the underlying SQLite call fails.

fn load_extension<P: AsRef<Path>>(
    &self,
    dylib_path: P,
    entry_point: Option<&str>
) -> Result<()>

Load the SQLite extension at dylib_path. dylib_path is passed through to sqlite3_load_extension, which may attempt OS-specific modifications if the file cannot be loaded directly.

If entry_point is None, SQLite will attempt to find the entry point. If it is not None, the entry point will be passed through to sqlite3_load_extension.

Example

fn load_my_extension(conn: &Connection) -> Result<()> {
    let _guard = try!(LoadExtensionGuard::new(conn));

    conn.load_extension("my_sqlite_extension", None)
}

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 Send for Connection

impl Drop for Connection

fn drop(&mut self)

Executes the destructor for this type.

impl Debug for Connection

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

Formats the value using the given formatter.