Struct rusqlite::Savepoint

pub struct Savepoint<'conn> { /* private fields */ }

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

impl<'conn> Savepoint<'conn>

pub fn new(conn: &mut Connection) -> Result<Savepoint<'_>>

Begin a new savepoint. Can be nested.

pub fn with_name<T: Into<String>>(
    conn: &mut Connection,
    name: T
) -> Result<Savepoint<'_>>

Begin a new savepoint with a user-provided savepoint name.

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

Begin a nested savepoint.

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

Begin a nested savepoint with a user-provided savepoint name.

pub fn drop_behavior(&self) -> DropBehavior

Get the current setting for what happens to the savepoint when it is dropped.

pub fn set_drop_behavior(&mut self, drop_behavior: DropBehavior)

Configure the savepoint to perform the specified action when it is dropped.

pub fn commit(self) -> Result<()>

A convenience method which consumes and commits a savepoint.

pub fn rollback(&mut self) -> Result<()>

A convenience method which rolls back a savepoint.

Note

Unlike Transactions, savepoints remain active after they have been rolled back, and can be rolled back again or committed.

pub fn finish(self) -> Result<()>

Consumes the savepoint, committing or rolling back according to the current setting (see drop_behavior).

Functionally equivalent to the Drop implementation, but allows callers to see any errors that occur.

Methods from Deref<Target = Connection>

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 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.

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

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.

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 = 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.

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)

Remove/finalize all prepared statements currently in the cache.

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 + UnwindSafe + '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<()> {
    db.create_scalar_function("halve", 1, true, |ctx| {
        let value = ctx.get::<f64>(0)?;
        Ok(value / 2f64)
    })?;

    let six_halved: f64 = db.query_row("SELECT halve(6)", NO_PARAMS, |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
    A: RefUnwindSafe + UnwindSafe,
    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<()>

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.

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

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

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.

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<P>(&self, sql: &str, params: P) -> Result<usize>where
    P: IntoIterator,
    P::Item: ToSql,

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, &dyn 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

Get the SQLite rowid of the most recent successful INSERT.

Uses sqlite3_last_insert_rowid under the hood.

pub fn query_row<T, P, F>(&self, sql: &str, params: P, f: F) -> Result<T>where
    P: IntoIterator,
    P::Item: ToSql,
    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'",
        NO_PARAMS,
        |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<'_, '_>) -> 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.

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_and_then<T, E, P, F>(
    &self,
    sql: &str,
    params: P,
    f: F
) -> Result<T, E>where
    P: IntoIterator,
    P::Item: ToSql,
    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'",
        NO_PARAMS,
        |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 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 = 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.

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<()> {
    conn.load_extension_enable()?;
    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<()>

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

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 = 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

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 get_interrupt_handle(&self) -> InterruptHandle

Get access to a handle that can be used to interrupt long running queries from another thread.

pub fn is_autocommit(&self) -> bool

Test for auto-commit mode. Autocommit mode is on by default.

Trait Implementations

impl<'conn> Deref for Savepoint<'conn>

type Target = Connection

The resulting type after dereferencing.

fn deref(&self) -> &Connection

Dereferences the value.

impl<'conn> Drop for Savepoint<'conn>

fn drop(&mut self)

Executes the destructor for this type.