Struct Connection 

pub struct Connection(/* private fields */);

A high-level DuckDB connection.

Connection wraps a RawConnection and exposes a safe, ergonomic API for opening databases, executing SQL, and creating appenders.

Example

use better_duck_core::connection::Connection;

let mut conn = Connection::open_in_memory().expect("open in-memory db");
conn.execute_batch("CREATE TABLE t (id INTEGER)").expect("create table");
conn.execute_batch("INSERT INTO t VALUES (1)").expect("insert");

Implementations

impl Connection

pub fn open<P: AsRef<Path>>(path: P) -> Result<Connection>

Opens a connection to a DuckDB database at the given file path.

Errors

Returns an error if the database cannot be opened or the path contains a nul byte.

pub fn open_with_flags<P: AsRef<Path>>( path: P, config: Config, ) -> Result<Connection>

Opens a connection to a DuckDB database at the given path with additional config.

Errors

Returns an error if the database cannot be opened or the path contains a nul byte.

impl Connection

pub fn open_in_memory() -> Result<Connection>

Opens an in-memory DuckDB connection.

Errors

Returns an error if the connection cannot be established.

pub fn open_in_memory_with_flags(config: Config) -> Result<Connection>

Opens an in-memory DuckDB connection with additional config.

Errors

Returns an error if the connection cannot be established.

impl Connection

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

Executes one or more SQL statements separated by semicolons.

The result of each statement is discarded. Use this for DDL (CREATE TABLE, DROP TABLE) and simple DML (INSERT, UPDATE, DELETE).

Errors

Returns an error if any statement fails to execute.

Example

let mut conn = Connection::open_in_memory()?;
conn.execute_batch("CREATE TABLE t (id INTEGER)")?;
conn.execute_batch("INSERT INTO t VALUES (1)")?;

pub fn execute(&mut self, sql: impl AsRef<str>) -> Result<DuckResult>

Prepares and executes a SQL statement, returning the result.

Works for all statement types:

• SELECT — iterate rows via the Iterator impl on DuckResult.
• INSERT / UPDATE / DELETE — check DuckResult::changes() for affected rows.
• DDL (CREATE TABLE, DROP TABLE, etc.) — .changes() returns 0, no rows.
• INSERT … RETURNING — both iterate rows and check .changes().

For parameterized statements use execute_with.

Errors

Returns an error if DuckDB cannot prepare or execute the statement.

Examples

let mut conn = Connection::open_in_memory()?;
conn.execute_batch("CREATE TABLE t (id INTEGER)")?;
let n = conn.execute("INSERT INTO t VALUES (1)")?.changes();
assert_eq!(n, 1);

pub fn execute_with( &mut self, sql: impl AsRef<str>, binds: &mut [&mut dyn AppendAble], ) -> Result<DuckResult>

Prepares and executes a parameterized SQL statement, returning the result.

Errors

Returns an error if preparation, binding, or execution fails.

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

Creates an appender for bulk-inserting rows into the given table and schema.

Errors

Returns an error if the table does not exist or the appender cannot be created.

impl Connection

pub fn close(&mut self) -> Result<()>

Closes the connection explicitly.

The connection is also closed automatically on drop.

Errors

Always returns Ok(()).

pub fn is_open(&self) -> bool

Returns true if the connection is open.

pub fn db(&self) -> &RawConnection

Returns a reference to the underlying RawConnection.

This provides access to low-level operations such as prepare.

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

Opens a second, independent connection to the same database as this one.

Cheap: one duckdb_connect call, no file I/O. See Database::connect for details on what “the same database” means for :memory: connections.

Errors

Returns an error if the connection cannot be established.

pub fn database(&self) -> Database

Returns a shareable handle to the database backing this connection.

Use Database::connect to open further connections to the same database — including, for :memory: databases, connections that observe the same data.

impl Connection

pub fn register_scalar_function<S: VScalar>(&mut self, name: &str) -> Result<()>

where S::State: Default,

Registers S as a scalar function named name, using S::State’s default value as the shared state for every overload.

Errors

Returns an error if name contains a NUL byte, a signature’s logical type cannot be built, or DuckDB rejects the registration (e.g. a name conflict).

pub fn register_scalar_function_with_state<S: VScalar>( &mut self, name: &str, state: S::State, ) -> Result<()>

where S::State: Clone,

Registers S as a scalar function named name, with explicit shared state. The state is cloned once per overload.

Errors

Returns an error if name contains a NUL byte, a signature’s logical type cannot be built, or DuckDB rejects the registration (e.g. a name conflict).

impl Connection

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

Registers T as a table function named name.

Errors

Returns an error if name contains a NUL byte, a parameter’s logical type cannot be built, or DuckDB rejects the registration (e.g. a name conflict).

Trait Implementations

impl Send for Connection