Struct duckdb::Connection [−][src]
pub struct Connection { /* fields omitted */ }
Expand description
A connection to a DuckDB database.
Implementations
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>,
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;
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(?);
pub fn pragma_update(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
pragma_value: &dyn ToSql
) -> Result<()>
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>,
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.
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.
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.
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
Auto Trait Implementations
impl !RefUnwindSafe for Connection
impl !Sync for Connection
impl Unpin for Connection
impl UnwindSafe for Connection
Blanket Implementations
Mutably borrows from an owned value. Read more