Struct duckdb::Connection

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

A connection to a DuckDB database.

Implementations

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;

Query the current rows/values of pragma_name.

Prefer PRAGMA function introduced in DuckDB 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 DuckDB 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.

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

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.

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

Begin a new savepoint with a specified name.

See savepoint.

Failure

Will return Err if the underlying DuckDB call fails.

Open a new connection to a DuckDB database.

Connection::open(path) is equivalent to Connection::open_with_flags(path, Config::default()).

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

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

Failure

Will return Err if the underlying DuckDB open call fails.

Open a new connection to a DuckDB database.

Failure

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

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

Failure

Will return Err if the underlying DuckDB 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 DuckDB 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.

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.

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

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.

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.

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.

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

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

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

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

Trait Implementations

Open a new db connection

Performs copy-assignment from source. Read more

Formats the value using the given formatter. 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 resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

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

Uses borrowed data to replace owned data, usually by cloning. Read more

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.