Struct rusqlite::Savepoint [−][src]
pub struct Savepoint<'conn> { /* fields omitted */ }
Expand description
Represents a savepoint on a database connection.
Note
Savepoints will roll back by default. Use commit
method to explicitly
commit the savepoint, or use set_drop_behavior
to change what happens
when the savepoint is dropped.
Example
fn perform_queries(conn: &mut Connection) -> Result<()> {
let sp = conn.savepoint()?;
do_queries_part_1(&sp)?; // sp causes rollback if this fails
do_queries_part_2(&sp)?; // sp causes rollback if this fails
sp.commit()
}
Implementations
Begin a new savepoint. Can be nested.
Begin a new savepoint with a user-provided savepoint name.
Begin a nested savepoint with a user-provided savepoint name.
Get the current setting for what happens to the savepoint when it is dropped.
Configure the savepoint to perform the specified action when it is dropped.
A convenience method which rolls back a savepoint.
Note
Unlike Transaction
s, savepoints remain active after they have been
rolled back, and can be rolled back again or committed.
Methods from Deref<Target = Connection>
pub fn backup<P: AsRef<Path>>(
&self,
name: DatabaseName<'_>,
dst_path: P,
progress: Option<fn(_: Progress)>
) -> Result<()>
This is supported on crate feature backup
only.
pub fn backup<P: AsRef<Path>>(
&self,
name: DatabaseName<'_>,
dst_path: P,
progress: Option<fn(_: Progress)>
) -> Result<()>
backup
only.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 blob_open<'a>(
&'a self,
db: DatabaseName<'_>,
table: &str,
column: &str,
row_id: i64,
read_only: bool
) -> Result<Blob<'a>>
This is supported on crate feature blob
only.
pub fn blob_open<'a>(
&'a self,
db: DatabaseName<'_>,
table: &str,
column: &str,
row_id: i64,
read_only: bool
) -> Result<Blob<'a>>
blob
only.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.
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.
Newly created connections currently have a default busy timeout of 5000ms, but this may be subject to change.
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.
Newly created connections default to a
busy_timeout()
handler with a timeout
of 5000ms, although this is subject to change.
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 = conn.prepare_cached("INSERT INTO People (name) VALUES (?)")?;
stmt.execute(["Joe Smith"])?;
}
{
// This will return the same underlying SQLite statement handle without
// having to prepare it again.
let mut stmt = conn.prepare_cached("INSERT INTO People (name) VALUES (?)")?;
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.
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.
Remove/finalize all prepared statements currently in the cache.
pub fn create_collation<C>(
&self,
collation_name: &str,
x_compare: C
) -> Result<()> where
C: Fn(&str, &str) -> Ordering + Send + UnwindSafe + 'static,
This is supported on crate feature collation
only.
pub fn create_collation<C>(
&self,
collation_name: &str,
x_compare: C
) -> Result<()> where
C: Fn(&str, &str) -> Ordering + Send + UnwindSafe + 'static,
collation
only.Add or modify a collation.
pub fn collation_needed(
&self,
x_coll_needed: fn(_: &Connection, _: &str) -> Result<()>
) -> Result<()>
This is supported on crate feature collation
only.
pub fn collation_needed(
&self,
x_coll_needed: fn(_: &Connection, _: &str) -> Result<()>
) -> Result<()>
collation
only.Collation needed callback
This is supported on crate feature collation
only.
collation
only.Remove collation.
Returns the current value of a config
.
- SQLITE_DBCONFIG_ENABLE_FKEY: return
false
ortrue
to indicate whether FK enforcement is off or on - SQLITE_DBCONFIG_ENABLE_TRIGGER: return
false
ortrue
to indicate whether triggers are disabled or enabled - SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER: return
false
ortrue
to indicate whether fts3_tokenizer are disabled or enabled - SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE: return
false
to indicate checkpoints-on-close are not disabled ortrue
if they are - SQLITE_DBCONFIG_ENABLE_QPSG: return
false
ortrue
to indicate whether the QPSG is disabled or enabled - SQLITE_DBCONFIG_TRIGGER_EQP: return
false
to indicate output-for-trigger are not disabled ortrue
if it is
Make configuration changes to a database connection
- SQLITE_DBCONFIG_ENABLE_FKEY:
false
to disable FK enforcement,true
to enable FK enforcement - SQLITE_DBCONFIG_ENABLE_TRIGGER:
false
to disable triggers,true
to enable triggers - SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER:
false
to disable fts3_tokenizer(),true
to enable fts3_tokenizer() - SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE:
false
(the default) to enable checkpoints-on-close,true
to disable them - SQLITE_DBCONFIG_ENABLE_QPSG:
false
to disable the QPSG,true
to enable QPSG - SQLITE_DBCONFIG_TRIGGER_EQP:
false
to disable output for trigger programs,true
to enable it
pub fn create_scalar_function<F, T>(
&self,
fn_name: &str,
n_arg: c_int,
flags: FunctionFlags,
x_func: F
) -> Result<()> where
F: FnMut(&Context<'_>) -> Result<T> + Send + UnwindSafe + 'static,
T: ToSql,
This is supported on crate feature functions
only.
pub fn create_scalar_function<F, T>(
&self,
fn_name: &str,
n_arg: c_int,
flags: FunctionFlags,
x_func: F
) -> Result<()> where
F: FnMut(&Context<'_>) -> Result<T> + Send + UnwindSafe + 'static,
T: ToSql,
functions
only.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<()> {
db.create_scalar_function(
"halve",
1,
FunctionFlags::SQLITE_UTF8 | FunctionFlags::SQLITE_DETERMINISTIC,
|ctx| {
let value = ctx.get::<f64>(0)?;
Ok(value / 2f64)
},
)?;
let six_halved: f64 = 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,
flags: FunctionFlags,
aggr: D
) -> Result<()> where
A: RefUnwindSafe + UnwindSafe,
D: Aggregate<A, T> + 'static,
T: ToSql,
This is supported on crate feature functions
only.
pub fn create_aggregate_function<A, D, T>(
&self,
fn_name: &str,
n_arg: c_int,
flags: FunctionFlags,
aggr: D
) -> Result<()> where
A: RefUnwindSafe + UnwindSafe,
D: Aggregate<A, T> + 'static,
T: ToSql,
functions
only.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 create_window_function<A, W, T>(
&self,
fn_name: &str,
n_arg: c_int,
flags: FunctionFlags,
aggr: W
) -> Result<()> where
A: RefUnwindSafe + UnwindSafe,
W: WindowAggregate<A, T> + 'static,
T: ToSql,
This is supported on crate features functions
and window
only.
pub fn create_window_function<A, W, T>(
&self,
fn_name: &str,
n_arg: c_int,
flags: FunctionFlags,
aggr: W
) -> Result<()> where
A: RefUnwindSafe + UnwindSafe,
W: WindowAggregate<A, T> + 'static,
T: ToSql,
functions
and window
only.Attach a user-defined aggregate window function to this database connection.
See https://sqlite.org/windowfunctions.html#udfwinfunc
for more
information.
This is supported on crate feature functions
only.
functions
only.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.
This is supported on crate feature limits
only.
limits
only.Returns the current value of a limit.
pub fn pragma_query_value<T, F>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
f: F
) -> Result<T> where
F: FnOnce(&Row<'_>) -> Result<T>,
pub fn pragma_query_value<T, F>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
f: F
) -> Result<T> where
F: FnOnce(&Row<'_>) -> Result<T>,
Query the current value of pragma_name
.
Some pragmas will return multiple rows/values which cannot be retrieved with this method.
Prefer PRAGMA function introduced in SQLite 3.20:
SELECT user_version FROM pragma_user_version;
Query the current rows/values of pragma_name
.
Prefer PRAGMA function introduced in SQLite 3.20:
SELECT * FROM pragma_collation_list;
Query the current value(s) of pragma_name
associated to
pragma_value
.
This method can be used with query-only pragmas which need an argument
(e.g. table_info('one_tbl')
) or pragmas which returns value(s)
(e.g. integrity_check
).
Prefer PRAGMA function introduced in SQLite 3.20:
SELECT * FROM pragma_table_info(?);
pub fn pragma_update<V>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
pragma_value: V
) -> Result<()> where
V: ToSql,
pub fn pragma_update<V>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
pragma_value: V
) -> Result<()> where
V: ToSql,
Set a new value to pragma_name
.
Some pragmas will return the updated value which cannot be retrieved with this method.
pub fn pragma_update_and_check<F, T, V>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
pragma_value: V,
f: F
) -> Result<T> where
F: FnOnce(&Row<'_>) -> Result<T>,
V: ToSql,
pub fn pragma_update_and_check<F, T, V>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
pragma_value: V,
f: F
) -> Result<T> where
F: FnOnce(&Row<'_>) -> Result<T>,
V: ToSql,
Set a new value to pragma_name
and return the updated value.
Only few pragmas automatically return the updated value.
Begin a new transaction with the default behavior (DEFERRED).
Attempt to open a nested transaction will result in a SQLite error.
Connection::transaction
prevents this at compile time by taking &mut self
, but Connection::unchecked_transaction()
may be used to defer
the checking until runtime.
See Connection::transaction
and Transaction::new_unchecked
(which can be used if the default transaction behavior is undesirable).
Example
fn perform_queries(conn: Rc<Connection>) -> Result<()> {
let tx = conn.unchecked_transaction()?;
do_queries_part_1(&tx)?; // tx causes rollback if this fails
do_queries_part_2(&tx)?; // tx causes rollback if this fails
tx.commit()
}
Failure
Will return Err
if the underlying SQLite call fails. The specific
error returned if transactions are nested is currently unspecified.
pub fn create_module<'vtab, T: VTab<'vtab>>(
&self,
module_name: &str,
module: &'static Module<'vtab, T>,
aux: Option<T::Aux>
) -> Result<()>
This is supported on crate feature vtab
only.
pub fn create_module<'vtab, T: VTab<'vtab>>(
&self,
module_name: &str,
module: &'static Module<'vtab, T>,
aux: Option<T::Aux>
) -> Result<()>
vtab
only.Register a virtual table implementation.
Step 3 of Creating New Virtual Table Implementations.
Convenience method to run multiple SQL statements (that cannot take any parameters).
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.
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
With positional params
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),
}
}
With positional params of varying types
fn update_rows(conn: &Connection) {
match conn.execute(
"UPDATE foo SET bar = 'baz' WHERE qux = ?1 AND quux = ?2",
params![1i32, 1.5f64],
) {
Ok(updated) => println!("{} rows were updated", updated),
Err(err) => println!("update failed: {}", err),
}
}
With named params
fn insert(conn: &Connection) -> Result<usize> {
conn.execute(
"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.
Returns the path to the database file, if one exists and is known.
Note that in some cases PRAGMA database_list is likely to be more robust.
👎 Deprecated: You can use execute
with named params now.
You can use execute
with named params now.
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
).
Failure
Will return Err
if sql
cannot be converted to a C-compatible string
or if the underlying SQLite call fails.
Get the SQLite rowid of the most recent successful INSERT.
Uses sqlite3_last_insert_rowid under the hood.
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.
Returns Err(QueryReturnedNoRows)
if no results are returned. If the
query truly is optional, you can call .optional()
on the result of
this to get a Result<Option<T>>
.
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, &dyn ToSql)],
f: F
) -> Result<T> where
F: FnOnce(&Row<'_>) -> Result<T>,
👎 Deprecated: You can use query_row
with named params now.
pub fn query_row_named<T, F>(
&self,
sql: &str,
params: &[(&str, &dyn ToSql)],
f: F
) -> Result<T> where
F: FnOnce(&Row<'_>) -> Result<T>,
You can use query_row
with named params now.
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.
Returns Err(QueryReturnedNoRows)
if no results are returned. If the
query truly is optional, you can call .optional()
on the result of
this to get a Result<Option<T>>
.
Failure
Will return Err
if sql
cannot be converted to a C-compatible string
or if the underlying SQLite call fails.
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(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.
Prepare a SQL statement for execution.
Example
fn insert_new_people(conn: &Connection) -> Result<()> {
let mut stmt = conn.prepare("INSERT INTO People (name) VALUES (?)")?;
stmt.execute(["Joe Smith"])?;
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.
This is supported on crate feature load_extension
only.
load_extension
only.Enable loading of SQLite extensions from both SQL queries and Rust.
You must call Connection::load_extension_disable
when you’re
finished loading extensions (failure to call it can lead to bad things,
see “Safety”), so you should strongly consider using
LoadExtensionGuard
instead of this function, automatically disables
extension loading when it goes out of scope.
Example
fn load_my_extension(conn: &Connection) -> Result<()> {
// Safety: We fully trust the loaded extension and execute no untrusted SQL
// while extension loading is enabled.
unsafe {
conn.load_extension_enable()?;
let r = conn.load_extension("my/trusted/extension", None);
conn.load_extension_disable()?;
r
}
}
Failure
Will return Err
if the underlying SQLite call fails.
Safety
TLDR: Don’t execute any untrusted queries between this call and
Connection::load_extension_disable
.
Perhaps surprisingly, this function does not only allow the use of
Connection::load_extension
from Rust, but it also allows SQL queries
to perform the same operation. For example, in the period
between load_extension_enable
and load_extension_disable
, the
following operation will load and call some function in some dynamic
library:
SELECT load_extension('why_is_this_possible.dll', 'dubious_func');
This means that while this is enabled a carefully crafted SQL query can be used to escalate a SQL injection attack into code execution.
Safely using this function requires that you trust all SQL queries run
between when it is called, and when loading is disabled (by
Connection::load_extension_disable
).
This is supported on crate feature load_extension
only.
load_extension
only.Disable loading of SQLite extensions.
See Connection::load_extension_enable
for an example.
Failure
Will return Err
if the underlying SQLite call fails.
pub unsafe fn load_extension<P: AsRef<Path>>(
&self,
dylib_path: P,
entry_point: Option<&str>
) -> Result<()>
This is supported on crate feature load_extension
only.
pub unsafe fn load_extension<P: AsRef<Path>>(
&self,
dylib_path: P,
entry_point: Option<&str>
) -> Result<()>
load_extension
only.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 (for example
converting "some/ext"
to "some/ext.so"
, "some\\ext.dll"
, …).
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<()> {
// Safety: we don't execute any SQL statements while
// extension loading is enabled.
let _guard = unsafe { LoadExtensionGuard::new(conn)? };
// Safety: `my_sqlite_extension` is highly trustworthy.
unsafe { conn.load_extension("my_sqlite_extension", None) }
}
Failure
Will return Err
if the underlying SQLite call fails.
Safety
This is equivalent to performing a dlopen
/LoadLibrary
on a shared
library, and calling a function inside, and thus requires that you trust
the library that you’re loading.
That is to say: to safely use this, the code in the extension must be sound, trusted, correctly use the SQLite APIs, and not contain any memory or thread safety errors.
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.
Safety
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
.
Get access to a handle that can be used to interrupt long running queries from another thread.
Test for auto-commit mode. Autocommit mode is on by default.
This is supported on crate feature modern_sqlite
only.
modern_sqlite
only.Determine if all associated prepared statements have been reset.
This is supported on crate feature modern_sqlite
only.
modern_sqlite
only.Flush caches to disk mid-transaction
Trait Implementations
type Target = Connection
type Target = Connection
The resulting type after dereferencing.
Dereferences the value.