Struct rusqlite::Connection [−][src]
pub struct Connection { /* fields omitted */ }
A connection to a SQLite database.
Methods
impl Connection
[src]
impl Connection
pub fn backup<P: AsRef<Path>>(
&self,
name: DatabaseName,
dst_path: P,
progress: Option<fn(_: Progress)>
) -> Result<()>
[src]
pub 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.
pub fn restore<P: AsRef<Path>, F: Fn(Progress)>(
&mut self,
name: DatabaseName,
src_path: P,
progress: Option<F>
) -> Result<()>
[src]
pub fn restore<P: AsRef<Path>, F: Fn(Progress)>(
&mut self,
name: DatabaseName,
src_path: P,
progress: Option<F>
) -> 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
[src]
impl Connection
pub fn blob_open<'a>(
&'a self,
db: DatabaseName,
table: &str,
column: &str,
row_id: i64,
read_only: bool
) -> Result<Blob<'a>>
[src]
pub fn blob_open<'a>(
&'a self,
db: DatabaseName,
table: &str,
column: &str,
row_id: i64,
read_only: bool
) -> Result<Blob<'a>>
Open a handle to the BLOB located in row_id
, 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
[src]
impl Connection
pub fn busy_timeout(&self, timeout: Duration) -> Result<()>
[src]
pub fn busy_timeout(&self, timeout: Duration) -> Result<()>
Set a busy handler that sleeps for a specified amount of time when a table is locked. The handler will sleep multiple times until at least "ms" milliseconds of sleeping have accumulated.
Calling this routine with an argument equal to zero turns off all busy
handlers.
There can only be a single busy handler for a particular database
connection at any given moment. If another busy handler was defined
(using busy_handler
) prior to calling this routine, that other
busy handler is cleared.
pub fn busy_handler(&self, callback: Option<fn(_: i32) -> bool>) -> Result<()>
[src]
pub fn busy_handler(&self, callback: Option<fn(_: i32) -> bool>) -> Result<()>
Register a callback to handle SQLITE_BUSY
errors.
If the busy callback is None
, then SQLITE_BUSY is returned immediately upon encountering the lock.
The argument to the busy
handler callback is the number of times that the
busy handler has been invoked previously for the
same locking event. If the busy callback returns false
, then no
additional attempts are made to access the
database and SQLITE_BUSY
is returned to the
application. If the callback returns true
, then another attempt
is made to access the database and the cycle repeats.
There can only be a single busy handler defined for each database
connection. Setting a new busy handler clears any previously set
handler. Note that calling busy_timeout()
or evaluating PRAGMA busy_timeout=N
will change the busy handler and thus
clear any previously set busy handler.
impl Connection
[src]
impl Connection
pub fn prepare_cached<'a>(&'a self, sql: &str) -> Result<CachedStatement<'a>>
[src]
pub 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.
pub fn set_prepared_statement_cache_capacity(&self, capacity: usize)
[src]
pub 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.
pub fn flush_prepared_statement_cache(&self)
[src]
pub fn flush_prepared_statement_cache(&self)
Remove/finalize all prepared statements currently in the cache.
impl Connection
[src]
impl Connection
pub 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> + Send + 'static,
T: ToSql,
[src]
pub 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> + Send + 'static,
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.
pub 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,
[src]
pub 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.
pub fn remove_function(&self, fn_name: &str, n_arg: c_int) -> Result<()>
[src]
pub 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
[src]
impl Connection
pub fn limit(&self, limit: Limit) -> i32
[src]
pub fn limit(&self, limit: Limit) -> i32
Returns the current value of a limit.
pub fn set_limit(&self, limit: Limit, new_val: i32) -> i32
[src]
pub 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
[src]
impl Connection
pub fn trace(&mut self, trace_fn: Option<fn(_: &str)>)
[src]
pub 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.
pub fn profile(&mut self, profile_fn: Option<fn(_: &str, _: Duration)>)
[src]
pub 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
[src]
impl Connection
pub fn transaction(&mut self) -> Result<Transaction>
[src]
pub 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.
pub fn transaction_with_behavior(
&mut self,
behavior: TransactionBehavior
) -> Result<Transaction>
[src]
pub 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.
pub fn savepoint(&mut self) -> Result<Savepoint>
[src]
pub 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.
pub fn savepoint_with_name<T: Into<String>>(
&mut self,
name: T
) -> Result<Savepoint>
[src]
pub 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
[src]
impl Connection
pub fn create_module<T: VTab>(
&self,
module_name: &str,
module: &Module<T>,
aux: Option<T::Aux>
) -> Result<()>
[src]
pub fn create_module<T: VTab>(
&self,
module_name: &str,
module: &Module<T>,
aux: Option<T::Aux>
) -> Result<()>
Register a virtual table implementation.
Step 3 of Creating New Virtual Table Implementations.
impl Connection
[src]
impl Connection
pub fn open<P: AsRef<Path>>(path: P) -> Result<Connection>
[src]
pub 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, OpenFlags::SQLITE_OPEN_READ_WRITE | OpenFlags::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]
pub 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.
pub fn open_with_flags<P: AsRef<Path>>(
path: P,
flags: OpenFlags
) -> Result<Connection>
[src]
pub 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.
pub fn open_in_memory_with_flags(flags: OpenFlags) -> Result<Connection>
[src]
pub 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.
pub fn execute_batch(&self, sql: &str) -> Result<()>
[src]
pub 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.
pub fn execute(&self, sql: &str, params: &[&ToSql]) -> Result<usize>
[src]
pub fn execute(&self, sql: &str, params: &[&ToSql]) -> Result<usize>
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<usize>
[src]
pub fn execute_named(
&self,
sql: &str,
params: &[(&str, &ToSql)]
) -> Result<usize>
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<usize> { 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]
pub fn last_insert_rowid(&self) -> i64
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]
pub 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.
pub fn query_row_named<T, F>(
&self,
sql: &str,
params: &[(&str, &ToSql)],
f: F
) -> Result<T> where
F: FnOnce(&Row) -> T,
[src]
pub 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.
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]
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>,
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]
pub fn query_row_safe<T, F>(
&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]
pub 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.
pub fn close(self) -> Result<(), (Connection, Error)>
[src]
pub 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.
pub fn load_extension_enable(&self) -> Result<()>
[src]
pub 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.
pub fn load_extension_disable(&self) -> Result<()>
[src]
pub 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.
pub fn load_extension<P: AsRef<Path>>(
&self,
dylib_path: P,
entry_point: Option<&str>
) -> Result<()>
[src]
pub 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.
pub unsafe fn handle(&self) -> *mut sqlite3
[src]
pub 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
.
pub fn is_autocommit(&self) -> bool
[src]
pub fn is_autocommit(&self) -> bool
Test for auto-commit mode. Autocommit mode is on by default.
Trait Implementations
Auto Trait Implementations
impl !Sync for Connection
impl !Sync for Connection