Struct rusqlite::Connection
[−]
[src]
pub struct Connection { /* fields omitted */ }
A connection to a SQLite database.
Methods
impl Connection
[src]
pub fn transaction(&mut self) -> Result<Transaction>
[src]
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.
pub fn transaction_with_behavior(
&mut self,
behavior: TransactionBehavior
) -> Result<Transaction>
[src]
&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.
pub fn savepoint(&mut self) -> Result<Savepoint>
[src]
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.
pub fn savepoint_with_name<T: Into<String>>(
&mut self,
name: T
) -> Result<Savepoint>
[src]
&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
[src]
pub fn prepare_cached<'a>(&'a self, sql: &str) -> Result<CachedStatement<'a>>
[src]
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.
pub fn set_prepared_statement_cache_capacity(&self, capacity: usize)
[src]
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.
pub fn flush_prepared_statement_cache(&self)
[src]
impl Connection
[src]
pub fn limit(&self, limit: Limit) -> i32
[src]
Returns the current value of a limit.
pub fn set_limit(&self, limit: Limit, new_val: i32) -> i32
[src]
Changes the limit to new_val
, returning the prior value of the limit.
impl Connection
[src]
pub fn open<P: AsRef<Path>>(path: P) -> Result<Connection>
[src]
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.
pub fn open_in_memory() -> Result<Connection>
[src]
Open a new connection to an in-memory SQLite database.
Failure
Will return Err
if the underlying SQLite open call fails.
pub fn open_with_flags<P: AsRef<Path>>(
path: P,
flags: OpenFlags
) -> Result<Connection>
[src]
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.
pub fn open_in_memory_with_flags(flags: OpenFlags) -> Result<Connection>
[src]
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.
pub fn execute_batch(&self, sql: &str) -> Result<()>
[src]
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.
pub fn execute(&self, sql: &str, params: &[&ToSql]) -> Result<c_int>
[src]
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.
pub fn execute_named(
&self,
sql: &str,
params: &[(&str, &ToSql)]
) -> Result<c_int>
[src]
&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.
pub fn last_insert_rowid(&self) -> i64
[src]
Get the SQLite rowid of the most recent successful INSERT.
Uses sqlite3_last_insert_rowid under the hood.
pub fn query_row<T, F>(&self, sql: &str, params: &[&ToSql], f: F) -> Result<T> where
F: FnOnce(&Row) -> T,
[src]
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.
pub fn query_row_named<T, F>(
&self,
sql: &str,
params: &[(&str, &ToSql)],
f: F
) -> Result<T> where
F: FnOnce(&Row) -> T,
[src]
&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.
pub 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>,
[src]
&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.
pub fn query_row_safe<T, F>(
&self,
sql: &str,
params: &[&ToSql],
f: F
) -> Result<T> where
F: FnOnce(&Row) -> T,
[src]
&self,
sql: &str,
params: &[&ToSql],
f: F
) -> Result<T> where
F: FnOnce(&Row) -> T,
: 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.
pub fn prepare<'a>(&'a self, sql: &str) -> Result<Statement<'a>>
[src]
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.
pub fn close(self) -> Result<(), (Connection, Error)>
[src]
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.
pub unsafe fn handle(&self) -> *mut sqlite3
[src]
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
.