Positional Parameters

DuckDB positional parameters are written $1, $2, … (or ?). Bind them with execute_with, passing values as &mut dyn AppendAble. Every DuckValue and the primitive Rust types (i32, f64, &str / String, bool, …) implement AppendAble, and mixed types coerce to &mut dyn AppendAble at the call site.

execute_with

execute_with(sql, binds: &mut [&mut dyn AppendAble]) -> Result<DuckResult>. Heterogeneous types are fine; binds fill $1, $2, … in slice order.

use better_duck_core::types::value::DuckValue;

let mut min_id = 1i32;
let mut label = String::from("gamma");
let matched = conn
    .execute_with(
        "SELECT id FROM events WHERE id >= $1 AND label = $2",
        &mut [&mut min_id, &mut label],
    )?
    .count();

Why &mut? Binding goes through DuckDB’s value API, and the AppendAble contract takes the value by mutable reference so it can hand ownership of a built duckdb_value to the FFI call without an extra copy. The slice itself is &mut for the same reason.

Binding an explicit NULL

use better_duck_core::types::value::DuckValue;

let mut null_bind = DuckValue::Null;
let coalesced = conn
    .execute_with("SELECT COALESCE($1, 'fallback') AS v", &mut [&mut null_bind])?
    .materialize()?;

An Option<T> also binds as Null / Some — None becomes SQL NULL.

The `params!` macro

With the derive feature, params![…] builds the &mut [&mut dyn AppendAble] slice for you, mixing literals, owned values, and Null without the &mut x as &mut dyn … boilerplate:

use better_duck_core::{params, types::value::DuckValue};

conn.execute_with(
    "INSERT INTO t VALUES ($1, $2, $3)",
    &mut params![1_i32, "hi".to_owned(), DuckValue::Null],
)?;

See helper macros for details.

insert — homogeneous bind-and-run

For a statement filled from a homogeneous iterator, insert is terser:

conn.insert::<i32, _>("INSERT INTO t VALUES ($1, $2)", [10, 20])?;

insert errors if no rows changed. Use execute_with when a zero-change result is valid, or when the bind values have different types. See executing SQL.

Errors

Wrong number of bound parameters → Error::InvalidParameterCount.
A value that doesn’t fit its target type → Error::IntegralValueOutOfRange or a ConversionError.

Connecting

Querying

Values & Types

Parameters & Statements

Writing Data

Columnar

Concurrency

Interop

Errors & Extensions

User-Defined Functions

Derives & Helpers

execute_with

Binding an explicit NULL

The `params!` macro

insert — homogeneous bind-and-run

Errors

See also

​execute_with

​Binding an explicit NULL

​The params! macro

​insert — homogeneous bind-and-run

​Errors

​See also

execute_with

Binding an explicit NULL

The `params!` macro

insert — homogeneous bind-and-run

Errors

See also