Struct PooledReadConnection 

pub struct PooledReadConnection { /* private fields */ }

Methods from Deref<Target = Connection>

pub fn backup<N, P, F>( &self, name: N, dst_path: P, progress: Option<F>, ) -> Result<(), Error>

where N: Name, P: AsRef<Path>, F: Fn(Progress),

Back up the name database to the given destination path.

If progress is not None / NO_PROGRESS, 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 busy_timeout(&self, timeout: Duration) -> Result<(), Error>

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.

pub fn column_exists<N>( &self, db_name: Option<N>, table_name: N, column_name: N, ) -> Result<bool, Error>

where N: Name,

Check if table_name.column_name exists.

db_name is main, temp, the name in ATTACH, or None to search all databases.

pub fn table_exists<N>( &self, db_name: Option<N>, table_name: N, ) -> Result<bool, Error>

where N: Name,

Check if table_name exists.

db_name is main, temp, the name in ATTACH, or None to search all databases.

pub fn column_metadata<N>( &self, db_name: Option<N>, table_name: N, column_name: N, ) -> Result<(Option<&CStr>, Option<&CStr>, bool, bool, bool), Error>

where N: Name,

Extract metadata of column at specified index

Returns:

• declared data type
• name of default collation sequence
• True if column has a NOT NULL constraint
• True if column is part of the PRIMARY KEY
• True if column is AUTOINCREMENT

pub fn db_config(&self, config: DbConfig) -> Result<bool, Error>

Returns the current value of a config.

• SQLITE_DBCONFIG_ENABLE_FKEY: return false or true to indicate whether FK enforcement is off or on
• SQLITE_DBCONFIG_ENABLE_TRIGGER: return false or true to indicate whether triggers are disabled or enabled
• SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER: return false or true 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 or true if they are
• SQLITE_DBCONFIG_ENABLE_QPSG: return false or true to indicate whether the QPSG is disabled or enabled
• SQLITE_DBCONFIG_TRIGGER_EQP: return false to indicate output-for-trigger are not disabled or true if it is

pub fn set_db_config( &self, config: DbConfig, new_val: bool, ) -> Result<bool, Error>

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 pragma_query_one<T>( &self, schema_name: Option<&str>, pragma_name: &str, ) -> Result<T, Error>

where T: FromSql,

Query the current value of pragma_name.

pub fn pragma_query_value<T, F>( &self, schema_name: Option<&str>, pragma_name: &str, f: F, ) -> Result<T, Error>

where F: FnOnce(&Row<'_>) -> Result<T, Error>,

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;

pub fn pragma_query<F>( &self, schema_name: Option<&str>, pragma_name: &str, f: F, ) -> Result<(), Error>

where F: FnMut(&Row<'_>) -> Result<(), Error>,

Query the current rows/values of pragma_name.

Prefer PRAGMA function introduced in SQLite 3.20: SELECT * FROM pragma_collation_list;

pub fn pragma<F, V>( &self, schema_name: Option<&str>, pragma_name: &str, pragma_value: V, f: F, ) -> Result<(), Error>

where F: FnMut(&Row<'_>) -> Result<(), Error>, V: ToSql,

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(?1);

pub fn pragma_update<V>( &self, schema_name: Option<&str>, pragma_name: &str, pragma_value: V, ) -> Result<(), Error>

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<&str>, pragma_name: &str, pragma_value: V, f: F, ) -> Result<T, Error>

where F: FnOnce(&Row<'_>) -> Result<T, Error>, V: ToSql,

Set a new value to pragma_name and return the updated value.

Only few pragmas automatically return the updated value.

pub fn unchecked_transaction(&self) -> Result<Transaction<'_>, Error>

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 transaction_state<N>( &self, db_name: Option<N>, ) -> Result<TransactionState, Error>

where N: Name,

Determine the transaction state of a database

pub fn execute_batch(&self, sql: &str) -> Result<(), Error>

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.

pub fn execute<P>(&self, sql: &str, params: P) -> Result<usize, Error>

where P: Params,

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 = ?1", [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.

pub fn path(&self) -> Option<&str>

Returns the path to the database file, if one exists and is known.

Returns Some("") for a temporary or in-memory database.

Note that in some cases PRAGMA database_list is likely to be more robust.

pub fn release_memory(&self) -> Result<(), Error>

Attempts to free as much heap memory as possible from the database connection.

This calls sqlite3_db_release_memory.

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, Error>

where P: Params, F: FnOnce(&Row<'_>) -> Result<T, Error>,

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_one<T, P, F>(&self, sql: &str, params: P, f: F) -> Result<T, Error>

where P: Params, F: FnOnce(&Row<'_>) -> Result<T, Error>,

Convenience method to execute a query that is expected to return exactly one row.

Returns Err(QueryReturnedMoreThanOneRow) if the query returns more than one row.

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>> (requires that the trait rusqlite::OptionalExtension is imported).

Failure

Will return Err 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: Params, 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(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(&self, sql: &str) -> Result<Statement<'_>, Error>

Prepare a SQL statement for execution.

Example

fn insert_new_people(conn: &Connection) -> Result<()> {
    let mut stmt = conn.prepare("INSERT INTO People (name) VALUES (?1)")?;
    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 prepare_with_flags( &self, sql: &str, flags: PrepFlags, ) -> Result<Statement<'_>, Error>

Prepare a SQL statement for execution.

Failure

Will return Err if sql cannot be converted to a C-compatible string or 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.

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.

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 changes(&self) -> u64

Return the number of rows modified, inserted or deleted by the most recently completed INSERT, UPDATE or DELETE statement on the database connection.

See https://www.sqlite.org/c3ref/changes.html

pub fn total_changes(&self) -> u64

Return the total number of rows modified, inserted or deleted by all completed INSERT, UPDATE or DELETE statements since the database connection was opened, including those executed as part of trigger programs.

See https://www.sqlite.org/c3ref/total_changes.html

pub fn is_autocommit(&self) -> bool

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

pub fn is_busy(&self) -> bool

Determine if all associated prepared statements have been reset.

pub fn cache_flush(&self) -> Result<(), Error>

Flush caches to disk mid-transaction

pub fn is_readonly<N>(&self, db_name: N) -> Result<bool, Error>

where N: Name,

Determine if a database is read-only

pub fn db_name(&self, index: usize) -> Result<String, Error>

Return the schema name for a database connection

Failure

Return an Error::InvalidDatabaseIndex if index is out of range.

pub fn is_interrupted(&self) -> bool

Determine whether an interrupt is currently in effect

pub unsafe fn set_clientdata<T, N>( &self, name: N, data: Option<T>, ) -> Result<*mut T, Error>

where T: Send + 'static, N: Name,

Set client Data

Safety

This function is unsafe because it returns a raw pointer. You should not alter the callbacks stored by rusqlite.

pub unsafe fn get_clientdata<T, N>(&self, name: N) -> Result<Option<&T>, Error>

where N: Name,

Retrieve client data

Safety

Caller must be certain that data associated to name is of type T.

pub fn file_control<N>( &self, db_name: Option<N>, op_and_arg: FileControl<'_>, ) -> Result<(), Error>

where N: Name,

Low-level control of database files

See https://sqlite.org/c3ref/file_control.html for details.

Trait Implementations

impl Deref for PooledReadConnection

type Target = Connection

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Drop for PooledReadConnection

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.