Struct Transaction

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

Represents a transaction on a database connection.

Note

Transactions will roll back by default. Use commit method to explicitly commit the transaction, or use set_drop_behavior to change what happens when the transaction is dropped.

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

Implementations

impl Transaction<'_>

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

Begin a new transaction. Cannot be nested; see savepoint for nested transactions.

Even though we don’t mutate the connection, we take a &mut Connection so as to prevent nested transactions on the same connection. For cases where this is unacceptable, Transaction::new_unchecked is available.

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

Starts a new savepoint, allowing nested transactions.

Note

Just like outer level transactions, savepoint transactions rollback by default.

Example

fn perform_queries(conn: &mut Connection) -> Result<()> {
    let mut tx = conn.transaction()?;

    {
        let sp = tx.savepoint()?;
        if perform_queries_part_1_succeeds(&sp) {
            sp.commit()?;
        }
        // otherwise, sp will rollback
    }

    tx.commit()
}

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

Create a new savepoint with a custom savepoint name. See savepoint().

pub fn drop_behavior(&self) -> DropBehavior

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

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

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

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

A convenience method which consumes and commits a transaction.

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

A convenience method which consumes and rolls back a transaction.

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

Consumes the transaction, 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 prepare_cached(&self, sql: &str) -> Result<CachedStatement<'_>>

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 DuckDB 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 DuckDB 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 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 DuckDB 3.20: SELECT user_version FROM pragma_user_version;

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

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

Query the current rows/values of pragma_name.

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

pub fn pragma<F>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, pragma_value: &dyn ToSql, f: F, ) -> Result<()>

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

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 DuckDB 3.20: SELECT * FROM pragma_table_info(?);

pub fn pragma_update( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, pragma_value: &dyn ToSql, ) -> Result<()>

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>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, pragma_value: &dyn ToSql, f: F, ) -> Result<T>

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

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<'_>>

Begin a new transaction with the default behavior (DEFERRED).

Attempt to open a nested transaction will result in a DuckDB 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 DuckDB call fails. The specific error returned if transactions are nested is currently unspecified.

pub fn register_table_function<T: VTab>(&self, name: &str) -> Result<()>

Register the given TableFunction with the current db

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

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 DuckDB call fails.

pub fn execute<P: Params>(&self, sql: &str, params: P) -> 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.

Example

With 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 params of varying types

fn update_rows(conn: &Connection) {
    match conn.execute("UPDATE foo SET bar = ? WHERE qux = ?", params![&"baz", 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 DuckDB call fails.

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

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

pub fn query_row<T, P, F>(&self, sql: &str, params: P, f: F) -> Result<T>

where P: Params, F: FnOnce(&Row<'_>) -> Result<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.

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 DuckDB 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 DuckDB call fails.

pub fn prepare(&self, sql: &str) -> Result<Statement<'_>>

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 DuckDB call fails.

pub fn appender(&self, table: &str) -> Result<Appender<'_>>

Create an Appender for fast import data default to use DatabaseName::Main

Example

fn insert_rows(conn: &Connection) -> Result<()> {
    let mut app = conn.appender("foo")?;
    app.append_rows([[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]])?;
    Ok(())
}

Failure

Will return Err if table not exists

pub fn appender_to_db(&self, table: &str, schema: &str) -> Result<Appender<'_>>

Create an Appender for fast import data

Example

fn insert_rows(conn: &Connection) -> Result<()> {
    let mut app = conn.appender_to_db("foo", &DatabaseName::Main.to_string())?;
    app.append_rows([[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]])?;
    Ok(())
}

Failure

Will return Err if table not exists

pub fn is_autocommit(&self) -> bool

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

pub fn try_clone(&self) -> Result<Self>

Creates a new connection to the already-opened database.

pub fn version(&self) -> Result<String>

Returns the version of the DuckDB library

Trait Implementations

impl<'conn> Debug for Transaction<'conn>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for Transaction<'_>

type Target = Connection

The resulting type after dereferencing.

fn deref(&self) -> &Connection

Dereferences the value.

impl Drop for Transaction<'_>

fn drop(&mut self)

Executes the destructor for this type.