Struct CachedStatement 

pub struct CachedStatement { /* private fields */ }

A prepared statement suitable for caching and re-execution. A prepared statement that can be reset and re-executed with different bindings.

The statement is prepared on — and therefore belongs to — the connection passed to prepare. DuckDB scopes transactions to a connection, so the statement must never be prepared on a different one: doing so would execute outside any BEGIN/ROLLBACK the caller has open.

The statement retains that connection, so it cannot outlive it. Unlike a Statement, it carries no Rust lifetime, which lets it live in a StatementCache alongside the connection it was prepared on.

This type is used by Diesel statement cache (StatementCache<DuckDb, CachedStatement>).

Implementations

impl CachedStatement

pub fn prepare(conn: &RawConnection, sql: impl AsRef<str>) -> Result<Self>

Prepares sql against the given connection.

The statement is bound to conn and shares its transaction state.

Errors

Returns Error::DuckDBFailure if DuckDB cannot parse or plan the query, or Error::NulError if sql contains an interior nul byte.

pub fn pending(&self) -> Result<PendingResult<'_>>

Begins incremental (“pending”) execution of this statement.

Bind parameters first. The returned PendingResult borrows self, runs the query one task at a time, and materialises the final result on execute().

Errors

Returns an error if DuckDB cannot create the pending result.

pub fn into_pending(self) -> Result<OwnedPending>

Consumes this statement into an owned, 'static pending execution.

Unlike pending, the returned OwnedPending owns the statement, so it can be stepped across spawn_blocking dispatches by the async adapter.

Errors

Returns an error if DuckDB cannot create the pending result.

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

Resets all parameter bindings so the statement can be re-executed.

Errors

Returns Error::DuckDBFailure if the DuckDB clear-bindings call fails.

pub fn bind<T: AppendAble + ?Sized>( &mut self, idx: u64, value: &mut T, ) -> Result<()>

Binds value at the given 1-based parameter index.

Errors

Returns an error if the underlying DuckDB bind call fails or idx is out of range.

pub fn bind_named<T: AppendAble + ?Sized>( &mut self, name: &str, value: &mut T, ) -> Result<()>

Binds value to the parameter identified by name (e.g. $id → "id").

Resolves the name to its 1-based index via duckdb_bind_parameter_index, then binds there.

Errors

Error::InvalidParameterName if the statement has no such parameter, Error::NulError if name contains an interior nul, or a bind failure.

pub fn statement_type(&self) -> StatementType

Returns the kind of SQL statement this prepared statement holds.

pub fn parameter_count(&self) -> u64

Number of parameters in the statement.

pub fn parameter_name(&self, index: u64) -> Option<String>

The name of the parameter at the 1-based index, or None for a positional parameter or an out-of-range index.

pub fn parameter_type(&self, index: u64) -> duckdb_type

The coarse duckdb_type of the parameter at the 1-based index.

pub fn parameter_logical_type(&self, index: u64) -> Option<TypeInfo>

The lossless TypeInfo of the parameter at the 1-based index.

pub fn parameter_index(&self, name: &str) -> Result<u64>

Resolves a named parameter to its 1-based index.

Errors

Error::InvalidParameterName if unknown, Error::NulError on interior nul.

pub fn column_count(&self) -> u64

Number of result columns the statement will produce.

pub fn column_name(&self, index: u64) -> Option<String>

The name of the result column at index, if in range.

pub fn column_type(&self, index: u64) -> duckdb_type

The coarse duckdb_type of the result column at index.

pub fn column_logical_type(&self, index: u64) -> Option<TypeInfo>

The lossless TypeInfo of the result column at index.

pub fn execute(&mut self) -> Result<DuckResult>

Executes the prepared statement and returns 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 etc.) — .changes() returns 0, no rows to iterate.
• INSERT … RETURNING — iterate rows and/or call .changes().

Errors

Returns Error::DuckDBFailure if execution fails.

Trait Implementations

impl Drop for CachedStatement

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

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

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for CachedStatement