Struct AsyncConnection 

pub struct AsyncConnection { /* private fields */ }

An async facade over a Connection.

Every method dispatches to tokio::task::spawn_blocking, so the connection never blocks the async executor. The handle is cheap to clone; clones share one connection, serialized by an internal mutex.

Cancellation

Query control (query_control, interrupt) goes through a separate QueryControl source that does not take the connection mutex, so it works while a native query holds that mutex on a blocking thread.

The query-executing futures are cancel-on-drop: dropping one requests interruption of the native query via that control. Note the honest limitation — tokio::task::spawn_blocking tasks cannot be aborted, so dropping the future does not instantly stop native work; it signals DuckDB to interrupt and lets the blocking task wind down. The connection becomes usable again once that task releases the mutex.

Panics

These methods panic if called outside a Tokio runtime context, matching tokio::task::spawn_blocking.

Implementations

impl AsyncConnection

pub fn new(conn: Connection) -> AsyncConnection

Wraps an existing Connection for async use.

pub fn try_into_inner(self) -> Result<Connection, AsyncConnection>

Recovers the inner Connection if this is the last handle.

Returns self unchanged (as Err) if other clones of this handle exist.

pub fn query_control(&self) -> QueryControl

Returns a QueryControl for the query currently running (or next to run) on this connection.

Does not take the connection mutex, so it can be called — and used to interrupt — while a query holds that mutex on a blocking thread.

pub fn interrupt(&self) -> bool

Requests interruption of the query currently running on this connection.

Returns true if an interrupt was signalled to DuckDB. Non-blocking and safe to call from any thread while a query runs.

pub async fn open<P>(path: P) -> Result<AsyncConnection>

where P: AsRef<Path> + Send + 'static,

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

Errors

Returns an error if the database cannot be opened.

pub async fn open_in_memory() -> Result<AsyncConnection>

Opens an in-memory DuckDB connection.

Errors

Returns an error if the connection cannot be established.

pub async fn with_connection<F, T>(&self, f: F) -> Result<T>

where F: FnOnce(&mut Connection) -> Result<T> + Send + 'static, T: Send + 'static,

Runs an arbitrary closure against the connection on a blocking thread.

This is the primitive every other method on this type is built from. Use it directly for transactions and anything the typed helpers don’t cover.

Errors

Returns an error if the closure returns one, or if the background task panics or is cancelled.

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

where S: Into<String> + Send,

Executes one or more SQL statements separated by semicolons.

Errors

Returns an error if any statement fails to execute.

pub async fn execute<S>(&self, sql: S) -> Result<ResultSet>

where S: Into<String> + Send,

Prepares and executes a SQL statement, materializing the result.

Errors

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

pub async fn execute_with<S>( &self, sql: S, binds: Vec<DuckValue>, ) -> Result<ResultSet>

where S: Into<String> + Send,

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

Errors

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

pub async fn execute_pending<S>(&self, sql: S) -> Result<ResultSet>

where S: Into<String> + Send,

Prepares and executes sql incrementally, stepping the query one DuckDB task per spawn_blocking dispatch and yielding to the async runtime between tasks.

This is the async form of CachedStatement::pending: rather than run the whole query inside one blocking call, each execute_task runs on its own blocking dispatch, so a long query neither monopolises a blocking thread nor blocks cancellation. Dropping the returned future stops stepping and, like every query path here, requests interruption of the in-flight task via the mutex-free QueryControl.

Errors

Returns an error if preparation or any execution task fails.

pub async fn with_appender<F, T>( &self, table: impl Into<String> + Send, schema: impl Into<String> + Send, f: F, ) -> Result<T>

where F: FnOnce(&mut Appender) -> Result<T> + Send + 'static, T: Send + 'static,

Runs a closure against a bulk-insert Appender for table/schema on a blocking thread.

The appender never leaves the closure — it holds raw FFI pointers, so it cannot be exposed as a standalone async handle.

Errors

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

pub fn progress(&self) -> Option<QueryProgress>

Reads the progress of the query currently running on this connection.

Returns None if no query is running. Non-blocking — reads through the mutex-free control source.

Trait Implementations

impl Clone for AsyncConnection

fn clone(&self) -> AsyncConnection

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.