Struct rusqlite::Connection

source · [−]
pub struct Connection { /* private fields */ }
Expand description

A connection to a SQLite database.

Implementations

This is supported on crate feature 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.

This is supported on crate feature backup only.

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.

This is supported on crate feature 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.

This is supported on crate feature collation only.

Add or modify a collation.

This is supported on crate feature collation only.

Collation needed callback

This is supported on crate feature collation only.

Remove collation.

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

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
This is supported on crate feature 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.

This is supported on crate feature 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.

This is supported on crate features 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.

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

Register a callback function to be invoked whenever a transaction is committed.

The callback returns true to rollback.

This is supported on crate feature hooks only.

Register a callback function to be invoked whenever a transaction is committed.

This is supported on crate feature hooks only.

Register a callback function to be invoked whenever a row is updated, inserted or deleted in a rowid table.

The callback parameters are:

  • the type of database update (SQLITE_INSERT, SQLITE_UPDATE or SQLITE_DELETE),
  • the name of the database (“main”, “temp”, …),
  • the name of the table that is updated,
  • the ROWID of the row that is updated.
This is supported on crate feature hooks only.

Register a query progress callback.

The parameter num_ops is the approximate number of virtual machine instructions that are evaluated between successive invocations of the handler. If num_ops is less than one then the progress handler is disabled.

If the progress callback returns true, the operation is interrupted.

This is supported on crate feature hooks only.

Register an authorizer callback that’s invoked as a statement is being prepared.

This is supported on crate feature limits only.

Returns the current value of a Limit.

This is supported on crate feature limits only.

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

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

Set a new value to pragma_name.

Some pragmas will return the updated value which cannot be retrieved with this method.

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

Only few pragmas automatically return the updated value.

This is supported on crate feature trace only.

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.

This is supported on crate feature trace only.

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.

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

Begin a new transaction with a specified behavior.

See transaction.

Failure

Will return Err if the underlying SQLite call fails.

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.

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)](Savepoint:: set_drop_behavior).

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

Will return Err if the underlying SQLite call fails.

Begin a new savepoint with a specified name.

See savepoint.

Failure

Will return Err if the underlying SQLite call fails.

This is supported on crate feature vtab only.

Register a virtual table implementation.

Step 3 of Creating New Virtual Table Implementations.

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

fn open_my_db() -> Result<()> {
    let path = "./my_db.db3";
    let db = Connection::open(&path)?;
    println!("{}", db.is_autocommit());
    Ok(())
}
Failure

Will return Err if path cannot be converted to a C-compatible string or if the underlying SQLite open call fails.

Open a new connection to an in-memory SQLite database.

Failure

Will return Err if the underlying SQLite open call fails.

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.

Open a new connection to a SQLite database using the specific flags and vfs name.

Database Connection for a description of valid flag combinations.

Failure

Will return Err if either path or vfs cannot be converted to a C-compatible string or if the underlying SQLite open call fails.

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.

Open a new connection to an in-memory SQLite database using the specific flags and vfs name.

Database Connection for a description of valid flag combinations.

Failure

Will return Err if vfs cannot be converted to a C-compatible string or if the underlying SQLite open call fails.

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.

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.

👎 Deprecated:

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.

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.

This is supported on crate feature 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.

Disable loading of SQLite extensions.

See Connection::load_extension_enable for an example.

Failure

Will return Err if the underlying SQLite call fails.

This is supported on crate feature 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.

Create a Connection from a raw handle.

The underlying SQLite database connection handle will not be closed when the returned connection is dropped/closed.

Safety

This function is unsafe because improper use may impact the 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.

Determine if all associated prepared statements have been reset.

This is supported on crate feature modern_sqlite only.

Flush caches to disk mid-transaction

Trait Implementations

Formats the value using the given formatter. Read more

Executes the destructor for this type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.