quack-rs: DuckDB extensions in Rust

A Rust SDK for building DuckDB loadable extensions — no C++ required.

What is quack-rs?

quack-rs is a Rust SDK for building DuckDB loadable extensions without C++ or CMake. It wraps DuckDB's C Extension API — the C interface DuckDB exposes to loadable extensions — in safe builders and RAII types, and guards against the FFI pitfalls documented in the Pitfall Catalog, so you can focus on extension logic.

DuckDB's own documentation acknowledges the gap:

"Writing a Rust-based DuckDB extension requires writing glue code in C++ and will force you to build through DuckDB's CMake & C++ based extension template. We understand that this is not ideal and acknowledge the fact that Rust developers prefer to work on pure Rust codebases."

— DuckDB Community Extensions FAQ

quack-rs closes that gap. No C++. No CMake. No glue code.

What you can build

Note: Window functions have no counterpart in DuckDB's public C Extension API and cannot be implemented from Rust (or any language) via that API. See Known Limitations.

Why does this exist?

quack-rs was extracted from duckdb-behavioral, a production DuckDB community extension. Building that extension revealed 16 undocumented pitfalls in DuckDB's Rust FFI surface — struct layouts, callback contracts, and initialization sequences that aren't covered anywhere in the DuckDB documentation or libduckdb-sys docs.

Three of those pitfalls caused extension-breaking bugs that passed 435 unit tests before being caught by end-to-end tests:

1. A SEGFAULT on load (wrong entry point sequence)
2. 6 of 7 functions silently not registered (undocumented function-set naming rule)
3. Wrong aggregate results under parallel plans (combine callback not propagating configuration fields to fresh target states)

quack-rs rules out the first two: entry_point! performs the correct initialization sequence, and the function-set builders name every member. The third lives in your own combine callback, so no API can prevent it; AggregateTestHarness::combine lets you test for it without DuckDB. The full list is in the Pitfall Catalog.

Key features

• Zero C++ — no CMakeLists.txt, no header files, no glue code
• Every function kind the C API can register — scalar, aggregate, table, cast, replacement scan, copy function (duckdb-1-5) — plus SQL macros
• Panic-safe FFI — the entry point and the callbacks quack-rs generates catch panics and report them as SQL errors; registration errors surface via Result
• RAII memory management — LogicalType and FfiState<T> prevent leaks and double-frees
• Type-safe builders — ScalarFunctionBuilder, AggregateFunctionBuilder, TableFunctionBuilder, CastFunctionBuilder, ReplacementScanBuilder
• SQL macros — register CREATE MACRO statements without any FFI callbacks
• Testable state — AggregateTestHarness<T> tests aggregate logic without a live DuckDB
• Scaffold generator — generates a complete community extension project (Cargo.toml, Makefile, CI, description.yml, tests) from one function call
• 31 pitfalls documented — every known DuckDB Rust FFI pitfall, with symptom, root cause and fix

Navigation

New to DuckDB extensions? → Start with Quick Start

Adding quack-rs to an existing project? → See Installation

Writing your first function? → See Scalar Functions or Aggregate Functions

Want SQL macros without FFI callbacks? → See SQL Macros

Submitting a community extension? → See Community Extensions

Something broke? → See Pitfall Catalog

Quick Start

This page takes you from an empty crate to a DuckDB loadable extension written in Rust, loaded into the DuckDB CLI, in three steps.

Prerequisites

• Rust ≥ 1.86.0 (MSRV) — install via rustup
• DuckDB CLI (for testing the built extension) — download

Step 1 — Add quack-rs to your extension

In your extension's Cargo.toml:

[dependencies]
quack-rs = "0.18"
libduckdb-sys = { version = ">=1.4.4, <2", features = ["loadable-extension"] }

[lib]
name = "my_extension"       # must match your extension name — see Pitfall P1
crate-type = ["cdylib", "rlib"]

[profile.release]
panic = "unwind"            # required — quack-rs's panic guards need unwinding (see Installation)
lto = true
opt-level = 3
codegen-units = 1
strip = true

Starting from scratch? The scaffold generator generates a complete community extension project, including this Cargo.toml.

Step 2 — Write the extension

#![allow(unused)]
fn main() {
// src/lib.rs
use quack_rs::entry_point;
use quack_rs::error::ExtensionError;
use quack_rs::scalar::ScalarFunctionBuilder;
use quack_rs::types::TypeId;
use quack_rs::vector::{VectorReader, VectorWriter};
use libduckdb_sys::{duckdb_connection, duckdb_function_info, duckdb_data_chunk, duckdb_vector};

/// Scalar function: double_it(BIGINT) → BIGINT
unsafe extern "C" fn double_it(
    _info: duckdb_function_info,
    input: duckdb_data_chunk,
    output: duckdb_vector,
) {
    // SAFETY: input is a valid data chunk provided by DuckDB.
    let reader = unsafe { VectorReader::new(input, 0) };
    let mut writer = unsafe { VectorWriter::new(output) };
    let row_count = reader.row_count();

    for row in 0..row_count {
        if unsafe { !reader.is_valid(row) } {
            unsafe { writer.set_null(row) };
            continue;
        }
        let value = unsafe { reader.read_i64(row) };
        unsafe { writer.write_i64(row, value * 2) };
    }
}

fn register(con: duckdb_connection) -> Result<(), ExtensionError> {
    unsafe {
        ScalarFunctionBuilder::new("double_it")
            .param(TypeId::BigInt)
            .returns(TypeId::BigInt)
            .function(double_it)
            .register(con)?;
    }
    Ok(())
}

entry_point!(my_extension_init_c_api, |con| register(con));
}

Step 3 — Build and test

# Build the extension
cargo build --release

# DuckDB refuses to LOAD a bare .so: append the metadata footer first.
# quack-rs ships the `append_metadata` binary for this step.
cargo install quack-rs --bin append_metadata
append_metadata target/release/libmy_extension.so my_extension.duckdb_extension \
    --abi-type C_STRUCT --extension-version v0.1.0 \
    --duckdb-version v1.2.0 --platform linux_amd64

# Load it; -unsigned allows a locally built, unsigned extension.
duckdb -unsigned -c "LOAD './my_extension.duckdb_extension'; SELECT double_it(21);"
# ┌───────────────┐
# │ double_it(21) │
# │     int64     │
# ├───────────────┤
# │            42 │
# └───────────────┘

macOS: the library is libmy_extension.dylib and the platform osx_arm64 (or osx_amd64). Windows: my_extension.dll and windows_amd64.

What's next?

• Learn how DuckDB calls your extension: Extension Anatomy
• Add an aggregate function: Aggregate Functions
• Add SQL macros without any callbacks: SQL Macros
• Generate a complete community extension project: Project Scaffold

Installation

This page covers the Cargo.toml dependencies and release-profile settings a DuckDB loadable extension built with quack-rs needs, the minimum Rust version, and the optional test features.

Adding quack-rs to an existing extension

Add the following to your extension's Cargo.toml:

[dependencies]
quack-rs = "0.18"
libduckdb-sys = { version = ">=1.4.4, <2", features = ["loadable-extension"] }

Why >=1.4.4, <2? Every DuckDB 1.4.x and 1.5.x release loads extensions built for C API version v1.2.0 (1.5.6 declares v1.5.6 and accepts every earlier one), so quack-rs supports both with a single bounded range. The <2 upper bound prevents silent adoption of a future major release whose C API may change in breaking ways — making any such upgrade an explicit, auditable decision. See Extension Anatomy.

Required Cargo.toml settings

Every DuckDB extension requires specific Cargo settings to link and behave correctly:

[lib]
name = "my_extension"       # ← must match extension name exactly (Pitfall P1)
crate-type = ["cdylib", "rlib"]
#             ^^^^^^  cdylib produces the .so/.dylib/.dll DuckDB loads
#                      rlib   optional: lets doctests, examples and tests/ link the crate

[profile.release]
panic = "unwind"            # REQUIRED — quack-rs catches panics at every FFI boundary;
                            #   "abort" makes that impossible (see below)
lto = true                  # recommended — reduces binary size, improves performance
opt-level = 3               # recommended
codegen-units = 1           # recommended — better optimisation, slower build
strip = true                # recommended — reduces binary size

Why panic = "unwind", not "abort"?

Every callback quack-rs generates (the *_callback! macros, the closure-based builders, FfiState's callbacks), and every entry point, runs your code inside std::panic::catch_unwind and turns a panic into an ordinary SQL error that DuckDB reports to the user. catch_unwind can only catch a panic that unwinds: under panic = "abort" the process terminates at the panic site, before any guard runs, taking the user's whole DuckDB session with it.

A raw unsafe extern "C" fn that you pass to a builder yourself (such as double_it in the Quick Start) is installed as written, with no guard. Define it with the matching macro (scalar_callback!, aggregate_update_callback!, …), which reports a panic as a SQL error, or wrap its body in quack_rs::callback::catch_ffi_panic and report the Err it returns yourself.

(A panic that escapes an extern "C" function without being caught is not undefined behaviour on Rust ≥ 1.81 — the runtime aborts the process — but that is exactly the outcome the guards exist to prevent.)

validate_release_profile rejects panic = "abort", and the scaffold generator emits panic = "unwind".

Minimum Supported Rust Version

quack-rs requires Rust ≥ 1.86.0.

1.86.0 is a ceiling as much as a floor. DuckDB's community-extension build workflow (_extension_distribution.yml in duckdb/extension-ci-tools) pins Rust 1.86.0 for its WebAssembly jobs, so an extension — and therefore quack-rs — must build on it; CI's msrv-vs-duckdb-ci job re-derives that pin and fails if the MSRV rises above it. The msrv job checks the crate with cargo +1.86.0 check, and the benchmark dev-dependency (criterion) needs 1.86 as well.

Install or update via:

rustup update stable
rustup default stable

Verify:

rustc --version   # must be ≥ 1.86.0

Development dependencies

To run SQL against your functions inside cargo test, enable one of quack-rs's test features as a dev-dependency:

[dev-dependencies]
# Compiles DuckDB from C++ source: no setup, slow cold build.
quack-rs = { version = "0.18", features = ["bundled-test"] }
# ...or link a prebuilt libduckdb instead (set DUCKDB_DOWNLOAD_LIB=1 or DUCKDB_LIB_DIR):
# quack-rs = { version = "0.18", features = ["bundled-test-prebuilt"] }

Either one initialises the loadable-extension dispatch table from the linked DuckDB, so testing::InMemoryDb works and the whole C API — including your own registration code — can be exercised in a test. Without them, any duckdb_* call in a cargo test process panics, because nothing has filled the dispatch table. See the Testing Guide.

Starting a new extension from scratch

Use the scaffold generator to produce a complete project with these settings, the build files and CI already in place.

Your First Extension

This page builds a DuckDB extension in Rust step by step, using hello-ext, the example extension bundled with quack-rs. The table lists four of the functions it registers, one of each major kind (the full list is in its README); this page walks through the aggregate and the scalar. The table function and the cast are covered in Table Functions and Cast Functions.

Full source: examples/hello-ext/src/lib.rs

Build and try it

cargo build --release --manifest-path examples/hello-ext/Cargo.toml

# DuckDB only loads files ending in `.duckdb_extension` that carry its
# 512-byte metadata footer; a bare `.so` is refused. Append the footer:
cargo run --bin append_metadata -- \
    examples/hello-ext/target/release/libhello_ext.so \
    hello_ext.duckdb_extension \
    --abi-type C_STRUCT --extension-version v0.1.0 \
    --duckdb-version v1.2.0 --platform linux_amd64

# An unsigned local build needs -unsigned (it must be a startup flag).
duckdb -unsigned

Then in the DuckDB CLI:

LOAD './hello_ext.duckdb_extension';

-- Aggregate: total words across all rows
SELECT word_count(sentence) FROM (
    VALUES ('hello world'), ('one two three'), (NULL)
) t(sentence);
-- → 5  (2 + 3; NULL contributes 0)

-- Scalar: first word of each row
SELECT first_word(sentence) FROM (
    VALUES ('hello world'), ('  padded  '), (''), (NULL)
) t(sentence);
-- → 'hello', 'padded', '', NULL

Overview

An extension has four parts:

1. State struct — holds data accumulated during aggregation (aggregate only)
2. Callbacks — update, combine, finalize (aggregate; ffi_state::<T>() supplies state_size, state_init and state_destroy) or a single function callback (scalar)
3. Registration — wire callbacks to DuckDB via AggregateFunctionBuilder / ScalarFunctionBuilder
4. Entry point — DuckDB's initialization hook, generated by entry_point!

Part 1 — Aggregate function: word_count

An aggregate function accumulates state across many rows and emits one result per group.

1a. The state struct

#![allow(unused)]
fn main() {
use quack_rs::prelude::*;
#[derive(Default, Debug)]
struct WordCountState {
    count: i64,
}

impl AggregateState for WordCountState {}
}

AggregateState is a marker trait with no methods; its supertraits require the state to be Default + Send + Sync + 'static. FfiState<WordCountState> stores it in the bytes DuckDB allocates for each group (boxing it only when it is large or over-aligned) and manages its lifecycle (size, init, destroy).

1b. state_size, state_init and state_destroy

These three callbacks are always identical boilerplate, so you do not write them: .ffi_state::<WordCountState>() on the builder (see Part 3) installs FfiState::<WordCountState>::size_callback, init_callback and destroy_callback together. Installing all three for one type in a single call means DuckDB never allocates space sized for one state and has it initialised as another.

size_callback returns FfiState::<WordCountState>::size() — one usize tag word followed by the state. A T aligned no more strictly than usize and at most 256 bytes (like WordCountState) is stored inline in the bytes DuckDB allocates per group; a larger or more strictly aligned T is boxed, and the slot holds the Box pointer. init_callback writes WordCountState::default() into the slot (or boxes it), then sets the tag — a value salted per state type, so a destructor only drops states that were initialised for its own T.

destroy_callback drops the T in each state (and its box, if the state is too large to be stored inline), clearing the state's tag first so a second call is a no-op.

1c. update — accumulate one batch

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default, Debug)] struct WordCountState { count: i64 }
impl AggregateState for WordCountState {}
fn count_words(s: &str) -> i64 { s.split_whitespace().count() as i64 }
unsafe extern "C" fn wc_update(
    _info: duckdb_function_info,
    input: duckdb_data_chunk,
    states: *mut duckdb_aggregate_state,
) {
    let reader = unsafe { VectorReader::new(input, 0) };
    let row_count = reader.row_count();

    for row in 0..row_count {
        if !unsafe { reader.is_valid(row) } {
            continue; // NULL input → skip (contributes 0 words)
        }
        let s = unsafe { reader.read_str(row) };
        let words = count_words(s);

        let state_ptr = unsafe { *states.add(row) };
        if let Some(st) = unsafe { FfiState::<WordCountState>::with_state_mut(state_ptr) } {
            st.count += words;
        }
    }
}
}

Key points:

• Check is_valid(row) before reading — never dereference an invalid (NULL) row
• VectorReader::new(chunk, col) gives column col from the chunk
• count_words is pure Rust — no unsafe, easy to unit-test separately

1d. combine — merge parallel results

Pitfall L1: DuckDB creates fresh target states before calling combine, set up by state_init (here WordCountState::default()), not copies of the source. You must copy all fields — not just the result field. In an aggregate with config fields (e.g., a histogram with a bin_width) you must also copy those, or results will be silently corrupted.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default, Debug)] struct WordCountState { count: i64 }
impl AggregateState for WordCountState {}
unsafe extern "C" fn wc_combine(
    _info: duckdb_function_info,
    source: *mut duckdb_aggregate_state,
    target: *mut duckdb_aggregate_state,
    count: idx_t,
) {
    for i in 0..count as usize {
        let src_ptr = unsafe { *source.add(i) };
        let tgt_ptr = unsafe { *target.add(i) };
        let src = unsafe { FfiState::<WordCountState>::with_state(src_ptr) };
        let tgt = unsafe { FfiState::<WordCountState>::with_state_mut(tgt_ptr) };
        if let (Some(s), Some(t)) = (src, tgt) {
            t.count += s.count;
            // If you add fields to WordCountState, combine them here too.
        }
    }
}
}

1e. finalize — write output

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default, Debug)] struct WordCountState { count: i64 }
impl AggregateState for WordCountState {}
unsafe extern "C" fn wc_finalize(
    _info: duckdb_function_info,
    source: *mut duckdb_aggregate_state,
    result: duckdb_vector,
    count: idx_t,
    offset: idx_t,
) {
    let mut writer = unsafe { VectorWriter::new(result) };

    for i in 0..count as usize {
        let state_ptr = unsafe { *source.add(i) };
        match unsafe { FfiState::<WordCountState>::with_state(state_ptr) } {
            Some(st) => unsafe { writer.write_i64(offset as usize + i, st.count) },
            None     => unsafe { writer.set_null(offset as usize + i) },
        }
    }
}
}

offset is DuckDB's output row offset — always use offset as usize + i, not just i.

Part 2 — Scalar function: first_word

A scalar function processes one data chunk and returns one output value per row. The callback receives the full chunk and an output vector (not per-row state pointers).

Key rule: always propagate NULL

If the input row is NULL, write NULL to output — never read from an invalid row.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
fn first_word(s: &str) -> &str { s.split_whitespace().next().unwrap_or("") }
unsafe extern "C" fn first_word_scalar(
    _info: duckdb_function_info,
    input: duckdb_data_chunk,
    output: duckdb_vector,
) {
    let reader = unsafe { VectorReader::new(input, 0) };
    let mut writer = unsafe { VectorWriter::new(output) };
    let row_count = reader.row_count();

    for row in 0..row_count {
        if !unsafe { reader.is_valid(row) } {
            unsafe { writer.set_null(row) }; // NULL in → NULL out
            continue;
        }
        let s = unsafe { reader.read_str(row) };
        unsafe { writer.write_varchar(row, first_word(s)) };
    }
}
}

The pure logic:

#![allow(unused)]
fn main() {
pub fn first_word(s: &str) -> &str {
    s.split_whitespace().next().unwrap_or("")
}
}

Note: set_null internally calls duckdb_vector_ensure_validity_writable before writing the null flag — this is required by DuckDB and handled for you by VectorWriter.

Part 3 — Registration

The snippets below register through the raw builders and entry_point!, which take a duckdb_connection. hello-ext itself uses the equivalent entry_point_v2!, whose closure receives a &Connection and registers each builder through the Registrar trait (con.register_aggregate(...), con.register_scalar(...)); see The Entry Point.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default, Debug)] struct WordCountState { count: i64 }
impl AggregateState for WordCountState {}
fn count_words(s: &str) -> i64 { s.split_whitespace().count() as i64 }
fn first_word(s: &str) -> &str { s.split_whitespace().next().unwrap_or("") }
unsafe extern "C" fn wc_update(_info: duckdb_function_info, input: duckdb_data_chunk,
    states: *mut duckdb_aggregate_state) {
    let reader = unsafe { VectorReader::new(input, 0) };
    for row in 0..reader.row_count() {
        if !unsafe { reader.is_valid(row) } { continue; }
        let words = count_words(unsafe { reader.read_str(row) });
        if let Some(st) = unsafe { FfiState::<WordCountState>::with_state_mut(*states.add(row)) } {
            st.count += words;
        }
    }
}
unsafe extern "C" fn wc_combine(_info: duckdb_function_info, source: *mut duckdb_aggregate_state,
    target: *mut duckdb_aggregate_state, count: idx_t) {
    for i in 0..count as usize {
        let src = unsafe { FfiState::<WordCountState>::with_state(*source.add(i)) };
        let tgt = unsafe { FfiState::<WordCountState>::with_state_mut(*target.add(i)) };
        if let (Some(s), Some(t)) = (src, tgt) { t.count += s.count; }
    }
}
unsafe extern "C" fn wc_finalize(_info: duckdb_function_info, source: *mut duckdb_aggregate_state,
    result: duckdb_vector, count: idx_t, offset: idx_t) {
    let mut writer = unsafe { VectorWriter::new(result) };
    for i in 0..count as usize {
        match unsafe { FfiState::<WordCountState>::with_state(*source.add(i)) } {
            Some(st) => unsafe { writer.write_i64(offset as usize + i, st.count) },
            None => unsafe { writer.set_null(offset as usize + i) },
        }
    }
}
unsafe extern "C" fn first_word_scalar(_info: duckdb_function_info, input: duckdb_data_chunk,
    output: duckdb_vector) {
    let reader = unsafe { VectorReader::new(input, 0) };
    let mut writer = unsafe { VectorWriter::new(output) };
    for row in 0..reader.row_count() {
        if !unsafe { reader.is_valid(row) } { unsafe { writer.set_null(row) }; continue; }
        unsafe { writer.write_varchar(row, first_word(reader.read_str(row))) };
    }
}
fn live_connection() -> libduckdb_sys::duckdb_connection {
    std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
    let (mut db, mut con) = (std::ptr::null_mut(), std::ptr::null_mut());
    unsafe {
        assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), libduckdb_sys::DuckDBSuccess);
        assert_eq!(libduckdb_sys::duckdb_connect(db, &mut con), libduckdb_sys::DuckDBSuccess);
    }
    con
}
/// First column of the first row, as BIGINT; `None` for NULL.
fn query_i64(con: libduckdb_sys::duckdb_connection, sql: &str) -> Option<i64> {
    let mut result = unsafe { quack_rs::query::query(con, sql) }.unwrap();
    let chunk = result.next_chunk().unwrap().unwrap();
    let reader = unsafe { chunk.reader(0) };
    unsafe { reader.is_valid(0).then(|| reader.read_i64(0)) }
}
unsafe fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), ExtensionError> {
    unsafe {
        AggregateFunctionBuilder::new("word_count")
            .param(TypeId::Varchar)
            .returns(TypeId::BigInt)
            .ffi_state::<WordCountState>() // state_size + init + destructor
            .update(wc_update)
            .combine(wc_combine)
            .finalize(wc_finalize)
            .register(con)?;

        ScalarFunctionBuilder::new("first_word")
            .param(TypeId::Varchar)
            .returns(TypeId::Varchar)
            .function(first_word_scalar)
            .register(con)?;
    }
    Ok(())
}
let con = live_connection();
unsafe { register(con) }.unwrap();
assert_eq!(query_i64(con, "SELECT word_count(s) FROM (VALUES ('hello world'), (NULL), ('one two three')) t(s)"), Some(5));
assert_eq!(query_i64(con, "SELECT length(first_word('  quack rs'))::BIGINT"), Some(5));
assert_eq!(query_i64(con, "SELECT count(*) FROM (SELECT first_word(NULL) AS w) WHERE w IS NULL"), Some(1));
// Many groups, so DuckDB runs combine on partial states.
assert_eq!(query_i64(con, "SELECT sum(c)::BIGINT FROM (SELECT word_count('a b') AS c FROM range(100000) GROUP BY range % 997)"), Some(200000));
}

Both builders call the DuckDB C API internally. register returns Err if DuckDB reports a failure — this propagates to the entry point and is surfaced to the user.

Part 4 — Entry point

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe fn register(_: duckdb_connection) -> Result<(), ExtensionError> { Ok(()) }
quack_rs::entry_point!(hello_ext_init_c_api, |con| unsafe { register(con) });
}

This one line expands to the equivalent of:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_connection, duckdb_extension_access, duckdb_extension_info};
use quack_rs::error::ExtensionError;
unsafe fn register(_: duckdb_connection) -> Result<(), ExtensionError> { Ok(()) }
#[no_mangle]
pub unsafe extern "C" fn hello_ext_init_c_api(
    info: duckdb_extension_info,
    access: *const duckdb_extension_access,
) -> bool {
    unsafe {
        quack_rs::entry_point::init_extension_with_policy(
            info, access, quack_rs::DUCKDB_API_VERSION,
            quack_rs::abi::AbiPolicy::Strict,
            |con| unsafe { register(con) },
        )
    }
}
}

Pass the full symbol name — hello_ext_init_c_api here. DuckDB looks up this exact symbol when loading the extension. See The Entry Point for the full initialization sequence.

Unit tests (no DuckDB process needed)

Test pure logic directly:

#![allow(unused)]
fn main() {
fn count_words(s: &str) -> i64 { s.split_whitespace().count() as i64 }
fn first_word(s: &str) -> &str { s.split_whitespace().next().unwrap_or("") }
#[test]
fn count_words_whitespace_variants() {
    assert_eq!(count_words("  hello  world  "), 2);
    assert_eq!(count_words("\t\nhello\tworld\n"), 2);
    assert_eq!(count_words("   "), 0); // all whitespace → 0
}

#[test]
fn first_word_empty_and_whitespace() {
    assert_eq!(first_word(""), "");
    assert_eq!(first_word("   "), "");
}
}

Test aggregate state with AggregateTestHarness:

#![allow(unused)]
fn main() {
use quack_rs::prelude::*;
use quack_rs::testing::AggregateTestHarness;
#[derive(Default, Debug)] struct WordCountState { count: i64 }
impl AggregateState for WordCountState {}
fn count_words(s: &str) -> i64 { s.split_whitespace().count() as i64 }
#[test]
fn word_count_null_rows_are_skipped() {
    // DuckDB passes NULL rows to `update`; the callback's `is_valid` check
    // skips them, so they never reach the state.
    let mut h = AggregateTestHarness::<WordCountState>::new();
    h.update(|s| s.count += count_words("hello"));
    // NULL row omitted — models the callback's `is_valid` skip
    h.update(|s| s.count += count_words("world"));
    assert_eq!(h.finalize().count, 2);
}

#[test]
fn word_count_combine() {
    let mut h1 = AggregateTestHarness::<WordCountState>::new();
    h1.update(|s| s.count += count_words("hello world")); // 2

    let mut h2 = AggregateTestHarness::<WordCountState>::new();
    h2.update(|s| s.count += count_words("one two three four")); // 4

    h2.combine(&h1, |src, tgt| tgt.count += src.count);
    assert_eq!(h2.finalize().count, 6);
}
}

Run all tests with:

cargo test --manifest-path examples/hello-ext/Cargo.toml

See the Testing Guide for the full test strategy.

Project Scaffold

quack_rs::scaffold::generate_scaffold generates every file of a new DuckDB community extension project in Rust — Cargo.toml, Makefile, CI workflow, description.yml, an example function and its tests — from a single function call.

What it generates

my_extension/
├── Cargo.toml                          # cdylib crate, dependencies, release profile
├── Makefile                            # delegates to cargo + extension-ci-tools
├── extension_config.cmake              # required by extension-ci-tools
├── src/
│   ├── lib.rs                          # entry point, example function, unit test
│   └── wasm_lib.rs                     # WASM staticlib shim
├── description.yml                     # community extension metadata
├── test/
│   └── sql/
│       └── my_extension.test           # SQLLogicTest for the example function
├── .github/
│   └── workflows/
│       └── extension-ci.yml            # cross-platform CI workflow
├── .gitmodules                         # extension-ci-tools submodule
├── .gitignore
└── .cargo/
    └── config.toml                     # Windows CRT static linking

Usage

generate_scaffold returns paths relative to the project root (Cargo.toml, src/lib.rs, ...) and writes nothing itself. Join them under the directory the project should live in — writing them relative to the current directory would overwrite whatever Cargo.toml and src/lib.rs are already there.

use quack_rs::scaffold::{ScaffoldConfig, generate_scaffold};
use std::path::Path;

fn main() {
    let config = ScaffoldConfig {
        name: "my_extension".to_string(),
        description: "My DuckDB extension".to_string(),
        version: "0.1.0".to_string(),
        license: "MIT".to_string(),
        maintainer: "Your Name".to_string(),
        github_repo: "yourorg/duckdb-my-extension".to_string(),
        excluded_platforms: vec![],
        // `target_duckdb_version`, `use_unstable_c_api` and `git_ref` default
        // to the stable-ABI settings; see `concepts/abi.md`.
        ..ScaffoldConfig::default()
    };

    let files = generate_scaffold(&config).expect("scaffold generation failed");

    // Everything goes under ./my_extension/, never into the current directory.
    let root = Path::new(&config.name);
    for file in &files {
        let path = root.join(&file.path);
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent).unwrap();
        }
        std::fs::write(&path, &file.content).unwrap();
        println!("created {}", path.display());
    }
}

ScaffoldConfig fields

Name validation

Extension names must satisfy all of:

• Match ^[a-z][a-z0-9_]*$ (no hyphens: the entry point is <name>_init_c_api)
• Not exceed 64 characters
• Be globally unique on community-extensions.duckdb.org

Use vendor-prefixed names to avoid collisions: myorg_analytics, not analytics.

The scaffold generator checks the first two rules before generating any files and returns an error if the name breaks one. Uniqueness is yours to check.

After scaffolding

cd my_extension
git init
git submodule add https://github.com/duckdb/extension-ci-tools.git extension-ci-tools
make configure
make release
make test

git submodule add is not optional in a new project: the scaffold writes .gitmodules, but git submodule update --init does nothing until the submodule has been added once (Pitfall P4). The generated Makefile stops with this command if the checkout is missing.

cargo test runs the generated unit test and make test runs test/sql/my_extension.test against a real DuckDB. Replace the example function in src/lib.rs with your own, give each new function a test in both places, and push to GitHub — CI runs automatically.

Excluded platforms

Some extensions cannot be built for all platforms (e.g., extensions that depend on platform-specific system libraries, or WASM environments that lack threading).

#![allow(unused)]
fn main() {
use quack_rs::scaffold::ScaffoldConfig;

let config = ScaffoldConfig {
    excluded_platforms: vec![
        "wasm_mvp".to_string(),
        "wasm_eh".to_string(),
        "wasm_threads".to_string(),
    ],
    ..ScaffoldConfig::default()
};
}

Validate individual platform names with quack_rs::validate::validate_platform, or a semicolon-delimited string (as used in description.yml) with quack_rs::validate::validate_excluded_platforms_str.

Extension Anatomy

A DuckDB loadable extension is a shared library (.so / .dylib / .dll) that DuckDB loads at runtime. This page covers what DuckDB expects of a Rust extension built on the C Extension API: the entry-point symbol, the initialization sequence, the loadable-extension dispatch table, and version and binary compatibility.

The initialization sequence

When DuckDB loads your extension, it:

1. Opens the shared library and looks up the symbol {name}_init_c_api, where {name} is the extension name
2. Calls that function with an info handle and a pointer to a duckdb_extension_access struct (the set_error, get_database and get_api callbacks)
3. Your function must:
   1. Call duckdb_rs_extension_api_init(info, access, api_version) to initialize the dispatch table
   2. Get the duckdb_database handle via access.get_database(info)
   3. Open a duckdb_connection via duckdb_connect
   4. Register functions on that connection
   5. Disconnect
   6. Return true (success) or false (failure), reporting any error through access.set_error

quack_rs::entry_point::init_extension performs this sequence. It also checks the C API layout before registration (see ABI Compatibility) and converts a panic in your registration code into a load error. The entry_point! macro generates the required #[no_mangle] extern "C" symbol:

#![allow(unused)]
fn main() {
use quack_rs::entry_point;
use quack_rs::error::ExtensionError;
fn register(_con: libduckdb_sys::duckdb_connection) -> Result<(), ExtensionError> { Ok(()) }
entry_point!(my_extension_init_c_api, |con| register(con));
// emits: #[no_mangle] pub unsafe extern "C" fn my_extension_init_c_api(...)
}

Symbol naming

The symbol name must be {extension_name}_init_c_api. Extension names use lowercase ASCII letters, digits and underscores only (no hyphens, which cannot appear in a C symbol). If the symbol is missing or misnamed, DuckDB fails to load the extension.

Extension name: "word_count_ext"
Required symbol: word_count_ext_init_c_api

Pass the full symbol name to entry_point!. The exported name then appears verbatim at the call site; the macro does not build identifiers at compile time.

The loadable-extension feature

With features = ["loadable-extension"], libduckdb-sys does not link DuckDB; every C API function dispatches through a table of function pointers instead:

Without feature:  duckdb_query(...)  →  calls linked libduckdb directly
With feature:     duckdb_query(...)  →  dispatches through an AtomicPtr table

The AtomicPtr table starts as null. The extension's entry point fills it by calling duckdb_rs_extension_api_init, which copies the pointers out of the API struct DuckDB provides. This means:

• Any call before duckdb_rs_extension_api_init panics with "DuckDB API not initialized or DuckDB feature omitted"
• In a plain cargo test, you cannot call any duckdb_* function — no DuckDB host process ever initializes the table

This is why quack-rs offers AggregateTestHarness for testing: it simulates the aggregate lifecycle in pure Rust, without calling the DuckDB API. For SQL-level tests, the bundled-test / bundled-test-prebuilt features link a real DuckDB and fill the table when InMemoryDb::open() runs (see Testing Guide).

Dependency model

graph TD
    EXT["your-extension"]
    QR["quack-rs"]
    LDS["libduckdb-sys >=1.4.4, <2<br/>{loadable-extension}<br/>(headers only — no linked library)"]

    EXT --> QR
    EXT --> LDS
    QR  --> LDS

The loadable-extension feature produces a shared library that does not statically link DuckDB. Instead, it receives DuckDB's function pointers at load time, so the extension runs inside the host DuckDB process and uses that process's DuckDB instance, memory and threads.

Version support

libduckdb-sys = ">=1.4.4, <2" — the bounded range is intentional.

Every DuckDB 1.4.x and 1.5.x release loads extensions built for C API version v1.2.0 (the version string passed to duckdb_rs_extension_api_init, quack_rs::DUCKDB_API_VERSION). DuckDB 1.5.6 declares C API version v1.5.6 and still accepts v1.2.0 extensions. CI loads the example extension into DuckDB 1.4.4, 1.5.0, 1.5.5 and the latest release. Using a range rather than an exact pin means:

• Extension authors can choose which libduckdb-sys release to build against (for example =1.4.4 for DuckDB 1.4.4, or ~1.10505.0 for DuckDB 1.5.5, which libduckdb-sys numbers 1.10505.x) and still resolve against quack-rs
• quack-rs itself doesn't force a DuckDB downgrade on users

The <2 upper bound is equally intentional: it prevents silent adoption of a future major release that may introduce breaking C API changes. Upgrading beyond the 1.x band requires an explicit quack-rs release that audits the new C API surface.

For your own extension's Cargo.toml: an extension that uses only the stable C API (the default quack-rs features) can keep the same ">=1.4.4, <2" range; this is what scaffold::generate_scaffold writes. An extension that enables the duckdb-1-5* features must pin libduckdb-sys to the bindings of the one DuckDB release it is stamped for (the scaffold writes ~1.10505.0 for v1.5.5). See ABI Compatibility.

Binary compatibility

Which DuckDB releases accept an extension binary depends on the ABI type stamped into its metadata footer:

• A C_STRUCT binary targeting C API v1.2.0 (the default, stable API only) loads into every DuckDB release whose C API version is at least v1.2.0 — all of 1.4.x and 1.5.x — on the platform it was built for
• A C_STRUCT_UNSTABLE binary loads only into the exact DuckDB release it names. Stamp builds that use the duckdb-1-5* features this way, so DuckDB itself refuses a mismatched release; quack-rs's runtime layout check is the backstop when the stamp is missing
• DuckDB checks the footer's platform and version fields at load time and refuses a mismatch
• Core and community extensions are signed; a binary you build locally is not
• To load an unsigned extension during development, start DuckDB with allow_unsigned_extensions enabled (duckdb -unsigned in the CLI); the setting cannot be changed on a running database
• The community extension CI builds and signs each extension for every supported platform

The Entry Point

Every DuckDB loadable extension exports one C-callable entry-point function, which DuckDB calls when it loads the extension. quack-rs generates it with the entry_point_v2! or entry_point! macro, or you can write it by hand around init_extension.

Option A: entry_point_v2! with Connection (recommended)

Added in v0.4.0.

The entry_point_v2! macro gives your closure a &Connection instead of a raw duckdb_connection. The Connection type implements the Registrar trait, which registers every kind of function, macro, cast, copy function and config option; replacement scans, which belong to the database rather than a connection, are Connection's own methods:

use quack_rs::entry_point_v2;
use quack_rs::connection::{Connection, Registrar};
use quack_rs::error::ExtensionError;

unsafe fn register(con: &Connection) -> Result<(), ExtensionError> {
    unsafe {
        con.register_scalar(/* ScalarFunctionBuilder */)?;
        con.register_aggregate(/* AggregateFunctionBuilder */)?;
        con.register_table(/* TableFunctionBuilder */)?;
        con.register_cast(/* CastFunctionBuilder */)?;
        con.register_scalar_set(/* ScalarFunctionSetBuilder */)?;
        con.register_aggregate_set(/* AggregateFunctionSetBuilder */)?;
        con.register_sql_macro(/* SqlMacro */)?;
        con.register_replacement_scan(/* callback, data, destructor */);
        // con.register_copy_function(/* CopyFunctionBuilder */)?;  // requires duckdb-1-5
    }
    Ok(())
}

entry_point_v2!(my_extension_init_c_api, |con| unsafe { register(con) });

(The register_* arguments above are placeholders, so that block is not compilable as written.) The macro emits the equivalent of the following; the real expansion also evaluates the policy and closure arguments inside a panic guard:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_extension_access, duckdb_extension_info};
use quack_rs::connection::Connection;
use quack_rs::error::ExtensionError;
unsafe fn register(_con: &Connection) -> Result<(), ExtensionError> { Ok(()) }
#[no_mangle]
pub unsafe extern "C" fn my_extension_init_c_api(
    info: duckdb_extension_info,
    access: *const duckdb_extension_access,
) -> bool {
    unsafe {
        quack_rs::entry_point::init_extension_v2_with_policy(
            info, access, quack_rs::DUCKDB_API_VERSION,
            quack_rs::abi::AbiPolicy::Strict,
            |con| unsafe { register(con) },
        )
    }
}
}

entry_point_v2!(name, policy, |con| ...) passes a different AbiPolicy.

Pass the full symbol name to the macro. The symbol {name}_init_c_api must match the name field in description.yml and the [lib] name in Cargo.toml.

Why Connection over raw duckdb_connection?

Option B: The entry_point! macro

The original macro passes a raw duckdb_connection to your closure. It performs the same initialization, but you pass the connection to each builder's .register():

#![allow(unused)]
fn main() {
use quack_rs::entry_point;
use quack_rs::error::ExtensionError;

fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), ExtensionError> {
    // Register each function on `con`, e.g. `unsafe { builder.register(con)? };`
    let _ = con;
    Ok(())
}

entry_point!(my_extension_init_c_api, |con| register(con));
}

Option C: Manual entry point

If you need full control (e.g., multiple registration functions, conditional logic):

#![allow(unused)]
fn main() {
use quack_rs::entry_point::init_extension;
use libduckdb_sys::{duckdb_extension_info, duckdb_extension_access};
use libduckdb_sys::duckdb_connection;
use quack_rs::error::ExtensionError;
fn register_scalar_functions(_: duckdb_connection) -> Result<(), ExtensionError> { Ok(()) }
fn register_aggregate_functions(_: duckdb_connection) -> Result<(), ExtensionError> { Ok(()) }
fn register_sql_macros(_: duckdb_connection) -> Result<(), ExtensionError> { Ok(()) }

#[no_mangle]
pub unsafe extern "C" fn my_extension_init_c_api(
    info: duckdb_extension_info,
    access: *const duckdb_extension_access,
) -> bool {
    unsafe {
        init_extension(info, access, quack_rs::DUCKDB_API_VERSION, |con| {
            register_scalar_functions(con)?;
            register_aggregate_functions(con)?;
            register_sql_macros(con)?;
            Ok(())
        })
    }
}
}

What init_extension does

flowchart TD
    A["<b>1. duckdb_rs_extension_api_init</b>(info, access, version)<br/>Fills the global AtomicPtr dispatch table"]
    L["<b>2. ABI layout check</b><br/>Applies the AbiPolicy (Strict by default)"]
    B["<b>3. access.get_database</b>(info)<br/>Returns the duckdb_database handle"]
    C["<b>4. duckdb_connect</b>(db, &amp;mut con)<br/>Opens a connection for function registration"]
    D["<b>5. register</b>(con) ← your closure<br/>A panic becomes an error"]
    E["<b>6. duckdb_disconnect</b>(&amp;mut con)<br/>Always runs, even if registration failed"]
    F{Error?}
    G["return <b>true</b>"]
    H["return <b>false</b><br/>error reported via access.set_error"]

    A --> L --> B --> C --> D --> E --> F
    L -->|refused| H
    F -->|no| G
    F -->|yes| H

    style G fill:#1c3b1c,stroke:#4a9e4a,color:#c8ecc8
    style H fill:#3b1c1c,stroke:#9e4a4a,color:#ecc8c8

An error from any step, including an Err or a panic from your closure in step 5, is reported to DuckDB via access.set_error, and the function returns false. DuckDB then fails the LOAD with that message. (When DuckDB itself detects the failure, as when get_database returns null, quack-rs returns false without overwriting DuckDB's own message.) The layout check in step 2 only runs when a duckdb-1-5* feature is enabled; see ABI Compatibility.

Registration is not transactional: functions registered before a failure stay registered for the life of the database. Do fallible setup work (reading configuration, building lookup tables) before the first register call.

The C API version constant

#![allow(unused)]
fn main() {
pub const DUCKDB_API_VERSION: &str = "v1.2.0";
}

Pitfall P2: This is the C API version, not the DuckDB release version. DuckDB 1.4.x and 1.5.0–1.5.5 declare C API version v1.2.0; 1.5.6 declares v1.5.6 and still loads extensions that target v1.2.0 (DuckDB accepts any C API version up to its own). A binary stamped with a DuckDB release version instead (-dv v1.5.5) is refused at LOAD by every DuckDB whose C API version is lower; quack-rs's append_metadata rejects such a value for C_STRUCT up front. See Pitfall P2.

No panics in the entry point

init_extension never panics. All error paths use Result and ?. If your registration closure returns Err or panics, the message is reported to DuckDB via access.set_error and the LOAD fails with an error instead of aborting the process. Catching a panic requires panic = "unwind" in your release profile (the scaffold's default).

Never use unwrap() or expect() in FFI callbacks. See Pitfall L3.

Error Handling

quack-rs reports every error through one type, ExtensionError, and the ExtResult<T> alias. This page covers creating and propagating errors, how they reach DuckDB, and why extension code must not panic.

ExtensionError

#![allow(unused)]
fn main() {
use quack_rs::error::{ExtensionError, ExtResult};
let (name, code) = ("my_fn", 1);
let some_std_error = std::fmt::Error;

// From a string literal
let e = ExtensionError::from("something went wrong");

// From a format string
let e = ExtensionError::new(format!("failed to register '{}': code {}", name, code));

// Wrapping another error
let e = ExtensionError::from_error(some_std_error);
}

ExtensionError implements:

• std::error::Error
• Display, Debug, Clone, PartialEq, Eq
• From<&str>, From<String>, From<Box<dyn Error>>, From<Box<dyn Error + Send + Sync>>
• From<std::io::Error>, From<std::ffi::NulError>, From<std::fmt::Error>

The From<std::io::Error> impl lets extensions that allocate runtime resources during initialization (a tokio runtime, for example) use ? without .map_err():

#![allow(unused)]
fn main() {
use quack_rs::connection::Connection;
use quack_rs::error::ExtensionError;
// A stand-in with tokio's signature: `Runtime::new() -> std::io::Result<Runtime>`.
mod tokio { pub mod runtime { pub struct Runtime;
    impl Runtime { pub fn new() -> std::io::Result<Self> { Ok(Runtime) } } } }
fn register_all(con: &Connection) -> Result<(), ExtensionError> {
    let _rt = tokio::runtime::Runtime::new()?; // ← io::Error → ExtensionError
    // ... register functions ...
    Ok(())
}
}

ExtResult<T>

A type alias for Result<T, ExtensionError>, used throughout the SDK:

#![allow(unused)]
fn main() {
use quack_rs::error::ExtensionError;
pub type ExtResult<T> = Result<T, ExtensionError>;
}

Propagating errors with ?

In your registration function:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_connection, duckdb_data_chunk, duckdb_function_info, duckdb_vector};
use quack_rs::prelude::*;
unsafe extern "C" fn my_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
fn register(con: duckdb_connection) -> Result<(), ExtensionError> {
    unsafe {
        ScalarFunctionBuilder::try_new("my_fn")?
            .param(TypeId::BigInt)
            .returns(TypeId::BigInt)
            .function(my_fn)
            .register(con)?;   // ← ? propagates registration errors

        SqlMacro::scalar("my_macro", &["x"], "x + 1")?
            .register(con)?;

        Ok(())
    }
}
}

If any registration call fails, ? returns the error from register, which init_extension then reports to DuckDB via access.set_error.

Error reporting to DuckDB

init_extension converts the ExtensionError to a C string for DuckDB's set_error callback, following the same rule as ExtensionError::to_c_string: a C string cannot hold a NUL byte, so each one is replaced with ? and the rest of the message is kept:

#![allow(unused)]
fn main() {
use quack_rs::error::ExtensionError;

let err = ExtensionError::new("bad\0input");
assert_eq!(err.to_c_string().to_str(), Ok("bad?input"));
}

DuckDB surfaces this string to the user as the extension load error.

No panics

The central rule of DuckDB extension development:

Never unwrap(), expect(), or panic!() in any code path that DuckDB may call.

A panic cannot unwind out of an extern "C" function: since Rust 1.81 the runtime aborts the process instead, taking the user's DuckDB session with it. quack-rs's callback macros and typed builders catch panics and turn them into SQL errors (which requires panic = "unwind" in the release profile), but that is a safety net for bugs, not an error-handling strategy.

Safe patterns

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_aggregate_state;
use quack_rs::aggregate::{AggregateState, FfiState};
use quack_rs::error::ExtensionError;
#[derive(Default)] struct MyState { count: u64 }
impl AggregateState for MyState {}
fn some_fallible_call() -> Result<u64, ExtensionError> { Ok(1) }
unsafe fn demo(state_ptr: duckdb_aggregate_state, maybe_count: Option<u64>)
    -> Result<(), ExtensionError> {
// ✅ Use Option methods
if let Some(s) = FfiState::<MyState>::with_state_mut(state_ptr) {
    s.count += 1;
}

// ✅ Use Result and ?
let value = some_fallible_call()?;

// ✅ Use unwrap_or / unwrap_or_else / map
let count = maybe_count.unwrap_or(0);

// ❌ Never in FFI callbacks
let s = FfiState::<MyState>::with_state_mut(state_ptr).unwrap(); // panics if None
Ok(())
}
}

In init_extension

init_extension reports every error via set_error and does not panic itself. It also runs your registration closure under catch_unwind, so a panic there becomes a load error rather than a process abort (with panic = "unwind").

Type System

quack-rs describes DuckDB column types with two types: TypeId, a plain enum of DuckDB's type ids, and LogicalType, an owned handle for full type descriptions such as DECIMAL(18, 3), LIST(VARCHAR) or a STRUCT. This page also maps each DuckDB type to its Rust type and vector read/write methods.

TypeId

TypeId is an enum covering DuckDB's column types (the GEOMETRY and VARIANT types added in DuckDB 1.5.x are exposed behind the duckdb-1-5-3 feature — see Known Limitations). The list below names the variants; it is a listing, not compilable code:

use quack_rs::types::TypeId;

TypeId::Boolean
TypeId::TinyInt     // i8
TypeId::SmallInt    // i16
TypeId::Integer     // i32
TypeId::BigInt      // i64
TypeId::UTinyInt    // u8
TypeId::USmallInt   // u16
TypeId::UInteger    // u32
TypeId::UBigInt     // u64
TypeId::HugeInt     // i128
TypeId::UHugeInt    // u128
TypeId::Float       // f32
TypeId::Double      // f64
TypeId::Timestamp
TypeId::TimestampTz
TypeId::TimestampS
TypeId::TimestampMs
TypeId::TimestampNs
TypeId::Date
TypeId::Time
TypeId::TimeTz
TypeId::Interval
TypeId::Varchar
TypeId::Blob
TypeId::Decimal
TypeId::Enum
TypeId::List
TypeId::Struct
TypeId::Map
TypeId::Uuid
TypeId::Union
TypeId::Bit
TypeId::Array
TypeId::TimeNs
TypeId::Any
TypeId::Varint           // SQL name BIGNUM (VARINT before DuckDB 1.4)
TypeId::SqlNull
TypeId::IntegerLiteral
TypeId::StringLiteral
TypeId::Geometry         // duckdb-1-5-3
TypeId::Variant          // duckdb-1-5-3

TypeId implements Copy, Clone, Debug, PartialEq, Eq, Hash and Display.

SQL name

#![allow(unused)]
fn main() {
use quack_rs::types::TypeId;
assert_eq!(TypeId::BigInt.sql_name(), "BIGINT");
assert_eq!(TypeId::Varchar.sql_name(), "VARCHAR");
assert_eq!(format!("{}", TypeId::Timestamp), "TIMESTAMP");
}

DuckDB constant

TypeId::to_duckdb_type() returns the DUCKDB_TYPE_* integer constant from libduckdb-sys. You rarely need this directly — it's called internally by LogicalType::new.

Reverse conversion

TypeId::from_duckdb_type(raw) converts a raw DUCKDB_TYPE constant back into a TypeId. It panics if the value does not match any known constant; TypeId::try_from_duckdb_type(raw) returns None instead.

#![allow(unused)]
fn main() {
use quack_rs::types::TypeId;

let type_id = TypeId::from_duckdb_type(libduckdb_sys::DUCKDB_TYPE_DUCKDB_TYPE_BIGINT);
assert_eq!(type_id, TypeId::BigInt);
}

LogicalType

LogicalType is an RAII wrapper around DuckDB's duckdb_logical_type. Creating one calls into DuckDB, so this block is compiled but not run:

#![allow(unused)]
fn main() {
use quack_rs::types::{LogicalType, TypeId};

let lt = LogicalType::new(TypeId::Varchar);
// lt.as_raw() returns the duckdb_logical_type pointer
// Drop calls duckdb_destroy_logical_type automatically
}

Pitfall L7: duckdb_create_logical_type allocates memory that must be freed with duckdb_destroy_logical_type. LogicalType's Drop implementation does this automatically, preventing the memory leak that occurs when calling the DuckDB C API directly. See Pitfall L7.

For a type a TypeId fully describes, pass the TypeId to a builder's param or returns method; the builder creates and destroys the LogicalType internally. For a parameterized type (DECIMAL, LIST, MAP, STRUCT, UNION, ENUM, ARRAY), build a LogicalType and pass it to param_logical or returns_logical.

Constructors

Every constructor except from_raw panics on invalid input (for example a composite TypeId passed to new, or a DECIMAL width outside 1–38) and has a try_* counterpart (try_new, try_decimal, try_struct_type, …) that returns Result<LogicalType, LogicalTypeError> instead. UNION types accept at most MAX_UNION_MEMBERS (255) members.

Introspection methods

All introspection methods are unsafe: they call into DuckDB, so the handle must be valid and the C API initialized.

Rust type ↔ DuckDB type mapping

When reading from or writing to vectors, use the corresponding VectorReader/VectorWriter method. The most common types:

The timestamp variants (TIMESTAMP_S, _MS, _NS, TIMESTAMPTZ), TIMETZ and DECIMAL have matching read_*/write_* methods as well.

NULLs are handled separately — see NULL Handling & Strings.

ABI Compatibility

This page explains DuckDB C Extension API ABI compatibility: which DuckDB releases a quack-rs extension binary can load into, and how quack-rs guards against a layout mismatch. A loadable extension does not link against DuckDB's symbols. DuckDB hands it a pointer to a duckdb_ext_api_v1 struct — an array of function pointers — and the extension calls through it.

Two things have to agree about that struct's layout: the header your extension was compiled against (whichever libduckdb-sys version Cargo resolved), and the DuckDB binary that is loading it. When they disagree, every call lands on the wrong slot.

The struct has two halves

The stable prefix is what makes "build once, load anywhere" possible. The unstable tail is not append-only:

DuckDB v1.5.6 declares all 546 slots stable for extensions that target C API v1.5.6 (earlier releases declared only the first 357 stable). The layout itself is unchanged from v1.5.2, and quack-rs targets C API v1.2.0, so the guard below still applies.

Every family since v1.2 changed the unstable tail, and twice (v1.5.0 and v1.5.2) an insertion in the middle shifted every later slot.

Which half are you using?

Everything quack-rs exposes by default lives in the stable prefix: scalar, aggregate, table and cast functions, vectors, data chunks, values, SQL macros, replacement scans, the query API and the datetime conversions.

The duckdb-1-5, duckdb-1-5-3 and duckdb-1-5-4 features wrap the unstable half — 130 of its 189 functions, covering scalar bind/init, copy functions in both directions, the Arrow C Data Interface bridge, catalog access, ErrorData, FileSystem, Expression, SelectionVector, config options, table descriptions, TIME_NS values and the client context.

abi::uses_unstable_api() reports which half a build uses. The book's own test build enables duckdb-1-5-4 (and therefore duckdb-1-5), so this block is compiled there but not run:

#![allow(unused)]
fn main() {
use quack_rs::abi;

// false unless `duckdb-1-5` is enabled.
assert!(!abi::uses_unstable_api());
}

Why DuckDB does not catch this for you

DuckDB validates the ABI metadata in your extension's footer:

So a C_STRUCT binary that touches the unstable region loads happily into the wrong DuckDB and then mis-dispatches. DuckDB's own extension-template-c says:

WARNING: When set to 1, the duckdb_extension.h from the TARGET_DUCKDB_VERSION must be used, using any other version of the header is unsafe.

Built against v1.5.0's headers and loaded into v1.5.5, an extension calling ClientContext::from_connection invokes duckdb_destroy_client_context on a duckdb_connection. In practice:

double free or corruption (out)
Aborted (core dumped)

What quack-rs does

Two layers.

Build metadata. If you enable duckdb-1-5, stamp the binary C_STRUCT_UNSTABLE with the DuckDB release you built against, so DuckDB refuses the wrong engine at install time. With extension-ci-tools, set in the Makefile:

USE_UNSTABLE_C_API=1
TARGET_DUCKDB_VERSION=v1.5.5

generate_scaffold writes this pairing from a ScaffoldConfig, and rejects a target_duckdb_version that does not match use_unstable_c_api:

#![allow(unused)]
fn main() {
use quack_rs::scaffold::ScaffoldConfig;

let config = ScaffoldConfig {
    name: "my_ext".to_string(),
    use_unstable_c_api: true,
    target_duckdb_version: "v1.5.5".to_string(),
    ..ScaffoldConfig::default()
};
}

Runtime guard. When a duckdb-1-5* feature is enabled, abi::check compares the compiled-in slot count against the layout the running engine uses, resolved from duckdb_library_version() — which lives at stable slot 7 and is therefore always dispatched correctly. (Without those features the check reports StableOnly and always passes.) The entry point applies it according to an AbiPolicy:

AllowUnknownEngine and Trust are only as safe as your knowledge of the engine: calling into the unstable region of a layout the extension was not built for is undefined behaviour. Before DuckDB v1.4.5 was in quack-rs's table, a v1.5.5 build loaded into v1.4.5 under AllowUnknownEngine and segfaulted.

The two lines below are alternatives: both define the same exported symbol, so they do not compile together.

use quack_rs::abi::AbiPolicy;

// Default: Strict.
quack_rs::entry_point!(my_ext_init_c_api, register);

// Explicit — appropriate when the binary is stamped C_STRUCT_UNSTABLE, because
// DuckDB already refuses to load it into the wrong release.
quack_rs::entry_point!(my_ext_init_c_api, AbiPolicy::Trust, register);

A refused load looks like this (a v1.5.0 build loaded into DuckDB v1.5.5):

DuckDB C extension API layout mismatch: this extension was built against a
duckdb_ext_api_v1 with 545 slots, but DuckDB v1.5.5 provides 546. The extension
uses the unstable region of the C API (quack-rs feature `duckdb-1-5`), whose slot
indices differ between these releases, so loading it would dispatch to the wrong
functions. Rebuild the extension against DuckDB v1.5.5. Stamp every build that
uses the unstable region with `--abi-type C_STRUCT_UNSTABLE --duckdb-version <the
DuckDB release it was built against>` (or `USE_UNSTABLE_C_API=1` with
extension-ci-tools) so DuckDB refuses a mismatched binary at install time.

For an engine older than v1.5.0 the advice changes: such an engine cannot run a duckdb-1-5 build at all, so the message says to build a variant without those features or to upgrade DuckDB.

Unknown DuckDB versions

Strict also refuses a DuckDB release quack-rs has no verified layout for — a newer release, or a -dev build. That is deliberate: DuckDB changed the unstable region in every minor release from 1.3.0 on, and in the 1.5.2 patch release, so "unknown" is not evidence of "compatible". The refusal lists the fixes, best first:

1. rebuild against the release you are targeting and set QUACK_RS_TARGET_DUCKDB_VERSION to it, which turns the check into a positive match without waiting for a quack-rs release;
2. upgrade quack-rs to a version whose layout table lists that release;
3. if the extension does not need the unstable region, build it without the duckdb-1-5 features: the stable prefix is laid out identically in every DuckDB since v1.2.0.

It never suggests AllowUnknownEngine or Trust, for the reason above.

scripts/check-abi-table.py re-derives quack-rs's layout table from every upstream release header and runs in CI, so the table tracks DuckDB.

Scalar Functions

A DuckDB scalar function returns one output value per input row, like the built-in length(), upper() or sin(). This page shows how to write one in Rust with quack-rs: as a raw callback registered through ScalarFunctionBuilder, as a safe closure with map1 / map2, or as a set of overloads with ScalarFunctionSetBuilder.

Function signature

DuckDB calls your scalar function once per data chunk (not once per row). The signature is:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn my_fn(
    info: duckdb_function_info,     // function metadata (rarely needed)
    input: duckdb_data_chunk,       // input data — one or more columns
    output: duckdb_vector,          // output vector — one value per input row
)
{}
}

Inside the function, you:

1. Create a VectorReader for each input column
2. Create a VectorWriter for the output
3. Loop over rows, checking for NULLs and transforming values

A panic that unwinds out of an extern "C" function aborts the process. Generate the function with scalar_callback!, which reports a panic as a SQL error, or use the closure constructors below (Error Handling).

Registration

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn my_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
use quack_rs::scalar::ScalarFunctionBuilder;
use quack_rs::types::TypeId;

unsafe fn register(con: duckdb_connection) -> Result<(), ExtensionError> {
    unsafe {
        ScalarFunctionBuilder::new("my_fn")
            .param(TypeId::BigInt)      // first parameter type
            .param(TypeId::BigInt)      // second parameter type (if any)
            .returns(TypeId::BigInt)    // return type
            .function(my_fn)            // callback
            .register(con)?;
    }
    Ok(())
}
}

Before calling duckdb_register_scalar_function, register checks that returns and function are set and that no parameter or return type is a bare composite TypeId (List, Decimal, …; use the *_logical methods for those). It also refuses a signature that duckdb_functions() already lists under the same name, built-ins included: DuckDB would otherwise silently replace that overload for every connection, or make every call ambiguous. If DuckDB reports failure, register returns Err.

Validated registration

For user-configurable function names (e.g., from a config file), use try_new:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn my_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
unsafe fn demo(con: duckdb_connection, name: &str) -> Result<(), ExtensionError> {
ScalarFunctionBuilder::try_new(name)?   // validates name before building
    .param(TypeId::Varchar)
    .returns(TypeId::Varchar)
    .function(my_fn)
    .register(con)?;
Ok(())
}
}

try_new validates the name as an unquoted SQL identifier: [A-Za-z_][A-Za-z0-9_]*, at most 256 characters, and not a DuckDB keyword that cannot be called as a function unquoted (order, coalesce). Mixed case is allowed (DuckDB itself ships formatReadableSize). new does not validate: it only panics if the name contains an interior NUL byte, so use it for names known at compile time.

Closures

ScalarFunctionBuilder::map1 / map2 / map1_str / map2_str / map1_opt / map2_opt build the whole function from a Rust closure and return a TypedScalarFunctionBuilder. Its signature is fixed by the closure's types, so it deliberately offers only name(), volatile() and register(con) — no returns, param, function, extra_info, bind or init, any of which could make DuckDB hand the closure vectors of a different type than it reads and writes. Register it with register(con), or through a Registrar with register_typed_scalar.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
ScalarFunctionBuilder::map1("double_it", |x: i64| x * 2)?.register(con)?;
Ok(())
}
}

Complete example: double_it(BIGINT) → BIGINT

#![allow(unused)]
fn main() {
use quack_rs::prelude::*;
fn live_connection() -> libduckdb_sys::duckdb_connection {
    std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
    let (mut db, mut con) = (std::ptr::null_mut(), std::ptr::null_mut());
    unsafe {
        assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), libduckdb_sys::DuckDBSuccess);
        assert_eq!(libduckdb_sys::duckdb_connect(db, &mut con), libduckdb_sys::DuckDBSuccess);
    }
    con
}
/// First column of the first row, as BIGINT; `None` for NULL.
fn query_i64(con: libduckdb_sys::duckdb_connection, sql: &str) -> Option<i64> {
    let mut result = unsafe { quack_rs::query::query(con, sql) }.unwrap();
    let chunk = result.next_chunk().unwrap().unwrap();
    let reader = unsafe { chunk.reader(0) };
    unsafe { reader.is_valid(0).then(|| reader.read_i64(0)) }
}
use quack_rs::vector::{VectorReader, VectorWriter};
use libduckdb_sys::{duckdb_function_info, duckdb_data_chunk, duckdb_vector};

unsafe extern "C" fn double_it(
    _info: duckdb_function_info,
    input: duckdb_data_chunk,
    output: duckdb_vector,
) {
    // SAFETY: DuckDB provides valid chunk and vector pointers.
    let reader = unsafe { VectorReader::new(input, 0) };   // column 0
    let mut writer = unsafe { VectorWriter::new(output) };
    let row_count = reader.row_count();

    for row in 0..row_count {
        if unsafe { !reader.is_valid(row) } {
            // NULL input → NULL output
            // SAFETY: row < row_count, writer is valid.
            unsafe { writer.set_null(row) };
            continue;
        }
        let value = unsafe { reader.read_i64(row) };
        unsafe { writer.write_i64(row, value * 2) };
    }
}
let con = live_connection();
unsafe {
    ScalarFunctionBuilder::new("double_it").param(TypeId::BigInt).returns(TypeId::BigInt)
        .function(double_it).register(con).unwrap();
}
assert_eq!(query_i64(con, "SELECT double_it(21)"), Some(42));
// From a column, not a literal: `double_it(NULL::BIGINT)` is constant-folded.
assert_eq!(query_i64(con, "SELECT double_it(i) FROM (VALUES (NULL::BIGINT)) t(i)"), None);
}

Multi-parameter example: add(BIGINT, BIGINT) → BIGINT

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn add(
    _info: duckdb_function_info,
    input: duckdb_data_chunk,
    output: duckdb_vector,
) {
    let col0 = unsafe { VectorReader::new(input, 0) };  // first param
    let col1 = unsafe { VectorReader::new(input, 1) };  // second param
    let mut writer = unsafe { VectorWriter::new(output) };

    for row in 0..col0.row_count() {
        if unsafe { !col0.is_valid(row) || !col1.is_valid(row) } {
            unsafe { writer.set_null(row) };
            continue;
        }
        let a = unsafe { col0.read_i64(row) };
        let b = unsafe { col1.read_i64(row) };
        unsafe { writer.write_i64(row, a + b) };
    }
}
}

VARCHAR example: shout(VARCHAR) → VARCHAR

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn shout(
    _info: duckdb_function_info,
    input: duckdb_data_chunk,
    output: duckdb_vector,
) {
    let reader = unsafe { VectorReader::new(input, 0) };
    let mut writer = unsafe { VectorWriter::new(output) };

    for row in 0..reader.row_count() {
        if unsafe { !reader.is_valid(row) } {
            unsafe { writer.set_null(row) };
            continue;
        }
        let s = unsafe { reader.read_str(row) };
        let upper = s.to_uppercase();
        unsafe { writer.write_varchar(row, &upper) };
    }
}
}

Overloading with function sets

If your function accepts different parameter types or arities, use ScalarFunctionSetBuilder to register multiple overloads under a single name:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn add_ints(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
unsafe extern "C" fn add_doubles(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
use quack_rs::scalar::{ScalarFunctionSetBuilder, ScalarOverloadBuilder};
use quack_rs::types::TypeId;

unsafe fn register(con: duckdb_connection) -> Result<(), ExtensionError> {
    unsafe {
        ScalarFunctionSetBuilder::new("my_add")
            .overload(
                ScalarOverloadBuilder::new()
                    .param(TypeId::Integer).param(TypeId::Integer)
                    .returns(TypeId::Integer)
                    .function(add_ints)
            )
            .overload(
                ScalarOverloadBuilder::new()
                    .param(TypeId::Double).param(TypeId::Double)
                    .returns(TypeId::Double)
                    .function(add_doubles)
            )
            .register(con)?;
    }
    Ok(())
}
}

Like AggregateFunctionSetBuilder, this builder calls duckdb_scalar_function_set_name on every individual function before adding it to the set (Pitfall L6).

ScalarOverloadBuilder has the same per-function settings as ScalarFunctionBuilder, applied to that overload only: null_handling, extra_info, varargs / varargs_logical, volatile, and (DuckDB 1.5+) bind / init. register checks every overload for a return type and a callback before it creates any DuckDB handle, and the error names the overload's index. It also refuses two overloads that accept the same call: the same argument types, or, with varargs, the same types at some argument count. f(BIGINT) and f(BIGINT, BIGINT...) both accept f(1), so they cannot share a set; DuckDB would accept the set and then fail every such call as ambiguous. An overload that matches an existing function's signature is refused as for ScalarFunctionBuilder.

NULL handling

Your callback receives NULL rows whatever the setting: under the default, DefaultNullHandling, it promises NULL-in-NULL-out and must write the NULLs itself — call chunk.propagate_nulls(&mut writer) at the end, or use the closure constructors (map1, map2 and their _str forms), which do it for you (Pitfall L8, NULL handling). A function that means to return non-NULL for NULL input (e.g., a COALESCE-like function) sets SpecialNullHandling:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn my_coalesce_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
use quack_rs::types::NullHandling;

ScalarFunctionBuilder::new("coalesce_custom")
    .param(TypeId::BigInt)
    .returns(TypeId::BigInt)
    .null_handling(NullHandling::SpecialNullHandling)
    .function(my_coalesce_fn)
    .register(con)?;
Ok(())
}
}

With SpecialNullHandling, the callback must check VectorReader::is_valid(row) itself and decide what each NULL input produces. The closure constructors map1_opt / map2_opt register SpecialNullHandling for you and pass the closure an Option (None for NULL); returning None writes NULL.

Complex parameter and return types

For scalar functions that accept or return parameterized types like LIST(BIGINT), use param_logical and returns_logical:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn flatten_list_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
use quack_rs::scalar::ScalarFunctionBuilder;
use quack_rs::types::{LogicalType, TypeId};

ScalarFunctionBuilder::new("flatten_list")
    .param_logical(LogicalType::list(TypeId::BigInt))  // LIST(BIGINT) input
    .returns(TypeId::BigInt)
    .function(flatten_list_fn)
    .register(con)?;
Ok(())
}
}

These methods are also available on ScalarOverloadBuilder for function sets:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn my_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
fn demo() {
let _ =
ScalarOverloadBuilder::new()
    .param(TypeId::Varchar)
    .returns_logical(LogicalType::list(TypeId::Timestamp))  // LIST(TIMESTAMP) output
    .function(my_fn)
;
}
}

Key points

• VectorReader::new(input, column_index) — the column index is zero-based
• Always check is_valid(row) before reading — skipping this reads garbage for NULL rows, and for VARCHAR/BLOB can follow a stale pointer
• set_null must be called for NULL outputs — it calls ensure_validity_writable automatically (Pitfall L4)
• read_bool returns bool — handles DuckDB's non-0/1 boolean bytes correctly (Pitfall L5)
• read_str handles both inline and pointer string formats automatically (Pitfall P7)

Varargs and volatility

These ScalarFunctionBuilder methods map to functions in DuckDB's stable C API (v1.2.0), so they need no feature flag and work on DuckDB 1.4.x and 1.5.x alike:

varargs(type_id: TypeId)

Declares that the function accepts a variable number of trailing arguments, all of the given TypeId. Maps to duckdb_scalar_function_set_varargs. A composite TypeId such as List or Decimal makes register return an error naming the varargs slot; use varargs_logical for those.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn concat_all_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
ScalarFunctionBuilder::new("concat_all")
    .varargs(TypeId::Varchar)
    .returns(TypeId::Varchar)
    .function(concat_all_fn)
    .register(con)?;
Ok(())
}
}

varargs_logical(logical_type: LogicalType)

Like varargs, but accepts a LogicalType for parameterized variadic arguments. Maps to duckdb_scalar_function_set_varargs.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn merge_lists_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
ScalarFunctionBuilder::new("merge_lists")
    .varargs_logical(LogicalType::list(TypeId::BigInt))
    .returns_logical(LogicalType::list(TypeId::BigInt))
    .function(merge_lists_fn)
    .register(con)?;
Ok(())
}
}

volatile()

Marks the function as volatile: DuckDB re-evaluates it for every row, even when its arguments are constant (as for random()), and never merges two identical calls in one query. Without it, DuckDB may evaluate a call with constant arguments only once. Maps to duckdb_scalar_function_set_volatile. Also available on the closure-built TypedScalarFunctionBuilder.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn random_int_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
ScalarFunctionBuilder::new("random_int")
    .returns(TypeId::Integer)
    .volatile()
    .function(random_int_fn)
    .register(con)?;
Ok(())
}
}

DuckDB 1.5.0 additions (duckdb-1-5)

The following ScalarFunctionBuilder methods are available when the duckdb-1-5 feature is enabled:

bind(bind_fn)

Sets a custom bind callback that runs at plan time. Use this to inspect argument types and set the return type dynamically. Maps to duckdb_scalar_function_set_bind.

The callback takes a RawScalarBindInfo (wrap it with ScalarBindInfo::new), not a bare duckdb_bind_info: DuckDB passes a table function's bind callback a different, larger struct, and a callback written for one kind of function corrupts memory on the other, so the types keep them apart. init takes a RawScalarInitInfo for the same reason. Generate panic-safe callbacks with scalar_bind_callback! and scalar_init_callback!; the table-function macros do not type-check here.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn dynamic_return_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
unsafe extern "C" fn my_bind_fn(_: quack_rs::scalar::RawScalarBindInfo) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
ScalarFunctionBuilder::new("dynamic_return")
    .varargs(TypeId::Varchar)
    .returns(TypeId::Varchar)   // default; overridden in bind
    .bind(my_bind_fn)
    .function(dynamic_return_fn)
    .register(con)?;
Ok(())
}
}

init(init_fn)

Sets a local-init callback invoked once per thread before execution begins. Use this to allocate per-thread state. Maps to duckdb_scalar_function_set_init.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn stateful_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
unsafe extern "C" fn my_init_fn(_: quack_rs::scalar::RawScalarInitInfo) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
ScalarFunctionBuilder::new("stateful_fn")
    .param(TypeId::BigInt)
    .returns(TypeId::BigInt)
    .init(my_init_fn)
    .function(stateful_fn)
    .register(con)?;
Ok(())
}
}

Typed bind data and local state

ScalarBindData<T> and ScalarLocalState<T> store a Rust value from the bind and init callbacks with a generated, panic-safe destructor, so no hand-written Box::from_raw is needed. A function that multiplies its argument by a factor fixed at bind time, and counts the rows each thread processes:

#![allow(unused)]
fn main() {
use quack_rs::prelude::*;
use quack_rs::scalar::{
    ScalarBindData, ScalarBindInfo, ScalarFunctionInfo, ScalarInitInfo, ScalarLocalState,
};

#[derive(Clone)]
struct Factor(i64);

quack_rs::scalar_bind_callback!(scaled_bind, |info| {
    // SAFETY: `info` is the argument of the running bind callback.
    let bind = unsafe { ScalarBindInfo::new(info) };
    ScalarBindData::set(&bind, Factor(10));
});

quack_rs::scalar_init_callback!(scaled_init, |info| {
    // SAFETY: `info` is the argument of the running init callback.
    let init = unsafe { ScalarInitInfo::new(info) };
    ScalarLocalState::set(&init, 0_u64); // rows this thread has processed
});

quack_rs::scalar_callback!(scaled, |info, input, output| {
    // SAFETY: DuckDB passes valid handles to the running callback.
    let fn_info = unsafe { ScalarFunctionInfo::new(info) };
    let chunk = unsafe { DataChunk::from_raw(input) };
    // SAFETY: `scaled_bind` stored a `Factor`, and nothing else did.
    let factor = unsafe { ScalarBindData::<Factor>::get(&fn_info) }.map_or(1, |f| f.0);
    // SAFETY: `scaled_init` stored a `u64` on this thread; no other borrow is live.
    if let Some(rows) = unsafe { ScalarLocalState::<u64>::get_mut(&fn_info) } {
        *rows += chunk.size() as u64;
    }
    let reader = unsafe { chunk.reader(0) };
    let mut writer = unsafe { VectorWriter::from_vector(output) };
    for row in 0..chunk.size() {
        // A NULL row holds an arbitrary value; `wrapping_mul` keeps it from
        // overflowing, and `propagate_nulls` below overwrites it with NULL.
        unsafe { writer.write_i64(row, reader.read_i64(row).wrapping_mul(factor)) };
    }
    unsafe { chunk.propagate_nulls(&mut writer) };
});

unsafe fn demo(con: libduckdb_sys::duckdb_connection) -> Result<(), ExtensionError> {
ScalarFunctionBuilder::new("scaled")
    .param(TypeId::BigInt)
    .returns(TypeId::BigInt)
    .bind(scaled_bind)
    .init(scaled_init)
    .function(scaled)
    .register(con)?;
Ok(())
}
}

• Bind data must be Clone + Send + Sync. Every executing thread reads the same value concurrently, and DuckDB copies the bound expression whenever the optimizer duplicates it (filter pushdown through a projection does). Without a copy callback the copy has no bind data at all, so set registers one that clones T. Wrap data that is expensive or impossible to clone in an Arc<T>.
• Local state must be Send: it is per thread, but may be freed on another.
• Call set at most once per callback. DuckDB overwrites the stored pointer on a second call without freeing the first value, so that value is leaked (never dropped).
• Bind data must depend only on the call's arguments (their values when constant, their types) and extra_info. DuckDB's CScalarFunctionBindData::Equals ignores bind data, so two calls with the same arguments — SELECT f(i), f(i) — are merged and share the first call's bind data. A bind callback that reads a counter, a clock or a random source needs the function marked volatile(), which stops the merge.

Extra info

Attach arbitrary data to a scalar function using extra_info, for example a locale or a configuration struct that parameterises its behaviour. The method is available on both ScalarFunctionBuilder and ScalarOverloadBuilder. The pointee must be Send + Sync: DuckDB passes the same pointer to the callback on every thread that runs the function, and the destructor runs on whichever thread releases it.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe extern "C" fn locale_upper_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
unsafe extern "C" fn my_destroy(p: *mut std::os::raw::c_void) {
    drop(unsafe { Box::from_raw(p.cast::<String>()) });
}
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
use std::os::raw::c_void;

let config = Box::into_raw(Box::new("en_US".to_string())).cast::<c_void>();
unsafe {
    ScalarFunctionBuilder::new("locale_upper")
        .param(TypeId::Varchar)
        .returns(TypeId::Varchar)
        .extra_info(config, Some(my_destroy))
        .function(locale_upper_fn)
        .register(con)?;
}
Ok(())
}
}

Inside the callback, retrieve the extra info with ScalarFunctionInfo::get_extra_info().

ScalarFunctionInfo

ScalarFunctionInfo wraps the duckdb_function_info handle provided to a scalar function callback. It exposes:

• get_extra_info() -> *mut c_void — retrieves the extra-info pointer set during registration
• set_error(message) — reports an error, which fails the query

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
use quack_rs::scalar::ScalarFunctionInfo;

unsafe extern "C" fn my_fn(
    info: duckdb_function_info,
    input: duckdb_data_chunk,
    output: duckdb_vector,
) {
    let info = unsafe { ScalarFunctionInfo::new(info) };
    let extra = unsafe { info.get_extra_info() };
    // ... use extra info, or report errors via info.set_error("...") ...
}
}

With the duckdb-1-5 feature, ScalarFunctionInfo also provides:

• get_bind_data() -> *mut c_void — retrieves bind data set during the bind callback
• get_state() -> *mut c_void — retrieves per-thread state set during the init callback

ScalarBindInfo (duckdb-1-5)

ScalarBindInfo wraps the duckdb_bind_info handle provided to a scalar function bind callback. It exposes:

• argument_count() -> u64 — number of arguments
• argument(index) -> Option<Expression> — the argument at index as an RAII Expression, before DuckDB casts it to the parameter type. On DuckDB before 1.5.5 it fails the bind and returns None, because those releases abort the process when the argument is a scalar subquery
• get_argument(index) -> duckdb_expression — the raw handle, with that hazard left to the caller
• get_extra_info() -> *mut c_void — the extra-info pointer from registration
• set_bind_data(data, destroy) — stores per-query data retrievable during execution
• set_bind_data_copy(copy) — the callback DuckDB uses to duplicate that data when it copies the bound expression; without one the copy's bind data is NULL
• set_error(message) — reports an error
• get_client_context() -> ClientContext — access to the connection's catalog and config

ScalarInitInfo (duckdb-1-5)

ScalarInitInfo wraps the duckdb_init_info handle provided to a scalar function init callback. It exposes:

• get_extra_info() -> *mut c_void — the extra-info pointer from registration
• get_bind_data() -> *mut c_void — the bind data from the bind callback
• set_state(state, destroy) — stores per-thread state retrievable during execution
• set_error(message) — reports an error
• get_client_context() -> ClientContext — access to the connection's catalog and config

Aggregate Functions

This page shows how to write a DuckDB aggregate function in Rust with quack-rs: the callbacks DuckDB calls, their signatures, and how AggregateFunctionBuilder registers them. An aggregate function reduces many rows to one value per group, like SUM(), COUNT() or AVG(). Because DuckDB aggregates in parallel, it also has a combine step that merges partial results from parallel workers.

Known DuckDB limitation

Out-of-bounds state reads. Two query shapes make DuckDB call every C-API aggregate's update with a state array holding one state while passing count > 1 rows, so the callback reads states[1..count] past the end of the array (undefined behaviour, in any C-API aggregate, whether built with quack-rs or by hand):

• Window aggregates whose frame is the whole partition, e.g. agg(x) OVER () — WindowConstantAggregator (src/function/window/window_constant_aggregator.cpp, ~lines 106 and 296–299 in DuckDB 1.5.5).
• Ordered aggregates, e.g. agg(x ORDER BY y) — src/function/aggregate/sorted_aggregate_function.cpp, ~lines 630–633.

Both paths pass a CONSTANT_VECTOR of states because the function has no simple_update (which the C API cannot set), and CAPIAggregateUpdate (src/main/capi/aggregate_function-c.cpp, ~lines 92–110) passes the vector's data pointer to the extension without flattening it. This is a defect in DuckDB's C API, not in quack-rs, and it cannot be detected from inside the callback: reading states[1] to check is itself the out-of-bounds read. Until DuckDB fixes it, do not use C-API aggregates in those two query shapes.

Reported upstream as duckdb/duckdb#26109.

The aggregate lifecycle

flowchart TD
    REG["<b>Registration</b><br/>AggregateFunctionBuilder<br/>→ duckdb_register_aggregate_function"]

    REG     --> SIZE
    SIZE    --> INIT
    INIT    --> UPDATE
    UPDATE  --> COMBINE
    COMBINE --> FINAL
    FINAL   --> DESTROY

    SIZE["<b>state_size</b>()<br/>How many bytes to allocate per group?"]
    INIT["<b>state_init</b>(state)<br/>Initialise a fresh state"]
    UPDATE["<b>update</b>(chunk, states[])<br/>Process one input batch<br/>(NULL rows included — check is_valid)"]
    COMBINE["<b>combine</b>(src[], tgt[], count)<br/>Merge partial results from parallel workers<br/>⚠️ Pitfall L1: target starts fresh — copy ALL config fields"]
    FINAL["<b>finalize</b>(states[], out, count, offset)<br/>Write count results at out[offset..], once per result batch"]
    DESTROY["<b>state_destroy</b>(states[], count)<br/>Free memory — after finalize and for combine<br/>sources after the merge (not every state: see Known Limitations)"]

    style COMBINE fill:#fff3cd,stroke:#e6ac00,color:#333

DuckDB may call combine many times as it merges partial results. A combine target holds whatever state_init set up, not a copy of the source, so combine must carry every field across (Pitfall L1). state_size is called whenever an operator sizes its state buffers, not once at registration, so it must always return the same value. destroy runs after finalize, and on combine's source states once they have been merged.

combine must leave its source states unchanged (Pitfall L15). A window's segment tree combines the same state into every frame that covers it, from several threads at once. A combine that moves data out of its source (mem::take, or zeroing a counter) is right for the first frame and wrong for the rest: in quack-rs's regression test, a sliding-window sum written that way was wrong on 4985 of 5000 rows. Read the source and copy or clone what the target needs.

Registration

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct MyState { count: i64 }
impl AggregateState for MyState {}
unsafe extern "C" fn update(_: duckdb_function_info, _: duckdb_data_chunk, _: *mut duckdb_aggregate_state) {}
unsafe extern "C" fn combine(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: *mut duckdb_aggregate_state, _: idx_t) {}
unsafe extern "C" fn finalize(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: duckdb_vector, _: idx_t, _: idx_t) {}
use quack_rs::aggregate::AggregateFunctionBuilder;
use quack_rs::types::TypeId;

unsafe fn register(con: duckdb_connection) -> Result<(), ExtensionError> {
    unsafe {
        AggregateFunctionBuilder::new("my_agg")
            .param(TypeId::BigInt)        // input type(s)
            .returns(TypeId::BigInt)      // output type
            .ffi_state::<MyState>()       // state_size + init + destructor
            .update(update)
            .combine(combine)
            .finalize(finalize)
            .register(con)?;
    }
    Ok(())
}
}

register returns an error if the return type or any of the five required callbacks (state_size, init, update, combine, finalize) is missing. The builder treats the destructor as optional (without one, register installs a no-op destructor; see Pitfall L13), but FfiState<T> needs its destroy_callback to drop each T. .ffi_state::<MyState>() sets state_size, init and destructor together from FfiState<MyState>, so the three cannot describe different states; see State Management. update, combine and finalize read the state through FfiState::<MyState>::with_state / with_state_mut with the same type.

Callback signatures

With FfiState<T> you do not write state_size, init or destroy yourself: ffi_state::<T>() installs FfiState::<T>::size_callback, init_callback and destroy_callback. The wrappers below show the signature DuckDB calls each one with, and what it does. update, combine and finalize are yours to write.

state_size

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct MyState { config_field: i64, accumulator: i64 }
impl MyState {
    fn accumulate(&mut self, v: i64) { self.accumulator += v; }
    fn result(&self) -> i64 { self.accumulator }
}
impl AggregateState for MyState {}
unsafe extern "C" fn state_size(info: duckdb_function_info) -> idx_t {
    unsafe { FfiState::<MyState>::size_callback(info) }
}
}

Returns the number of bytes DuckDB allocates per group, FfiState::<MyState>::size(): a tag word followed by MyState itself, padded to whole words (or, for a state larger than 256 bytes or aligned more strictly than usize, a Box<MyState> pointer).

state_init

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct MyState { config_field: i64, accumulator: i64 }
impl MyState {
    fn accumulate(&mut self, v: i64) { self.accumulator += v; }
    fn result(&self) -> i64 { self.accumulator }
}
impl AggregateState for MyState {}
unsafe extern "C" fn state_init(info: duckdb_function_info, state: duckdb_aggregate_state) {
    unsafe { FfiState::<MyState>::init_callback(info, state) };
}
}

Writes MyState::default() into the DuckDB-allocated state slot (or, for a boxed state, a Box holding it), then writes the tag that marks the slot initialised. A panic in default() is caught and reported to DuckDB as a query error.

update

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct MyState { config_field: i64, accumulator: i64 }
impl MyState {
    fn accumulate(&mut self, v: i64) { self.accumulator += v; }
    fn result(&self) -> i64 { self.accumulator }
}
impl AggregateState for MyState {}
unsafe extern "C" fn update(
    _info: duckdb_function_info,
    input: duckdb_data_chunk,
    states: *mut duckdb_aggregate_state,
) {
    let reader = unsafe { VectorReader::new(input, 0) };
    let row_count = reader.row_count();

    for row in 0..row_count {
        if unsafe { !reader.is_valid(row) } { continue; }
        let value = unsafe { reader.read_i64(row) };

        let state_ptr = unsafe { *states.add(row) };
        if let Some(st) = unsafe { FfiState::<MyState>::with_state_mut(state_ptr) } {
            st.accumulate(value);
        }
    }
}
}

states[row] is the state of that row's group; rows in the same group share one state. update receives NULL rows too, so skip rows where is_valid is false (see NULL Handling).

combine

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct MyState { config_field: i64, accumulator: i64 }
impl MyState {
    fn accumulate(&mut self, v: i64) { self.accumulator += v; }
    fn result(&self) -> i64 { self.accumulator }
}
impl AggregateState for MyState {}
unsafe extern "C" fn combine(
    _info: duckdb_function_info,
    source: *mut duckdb_aggregate_state,
    target: *mut duckdb_aggregate_state,
    count: idx_t,
) {
    for i in 0..count as usize {
        let src = unsafe { FfiState::<MyState>::with_state(*source.add(i)) };
        let tgt = unsafe { FfiState::<MyState>::with_state_mut(*target.add(i)) };
        if let (Some(s), Some(t)) = (src, tgt) {
            // ⚠️  MUST copy ALL fields — see Pitfall L1
            t.config_field = s.config_field;   // configuration
            t.accumulator  += s.accumulator;    // data
        }
    }
}
}

Pitfall L1 — critical: Target states are fresh states, set up by state_init (with FfiState<T>::init_callback, a T::default()), not copies of the source. You must copy every field, including configuration fields set during update. Forgetting even one config field produces silently wrong results. See Pitfall L1.

finalize

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct MyState { config_field: i64, accumulator: i64 }
impl MyState {
    fn accumulate(&mut self, v: i64) { self.accumulator += v; }
    fn result(&self) -> i64 { self.accumulator }
}
impl AggregateState for MyState {}
unsafe extern "C" fn finalize(
    _info: duckdb_function_info,
    source: *mut duckdb_aggregate_state,
    result: duckdb_vector,
    count: idx_t,
    offset: idx_t,
) {
    let mut writer = unsafe { VectorWriter::new(result) };
    for i in 0..count as usize {
        let state_ptr = unsafe { *source.add(i) };
        match unsafe { FfiState::<MyState>::with_state(state_ptr) } {
            Some(st) => unsafe { writer.write_i64(offset as usize + i, st.result()) },
            None     => unsafe { writer.set_null(offset as usize + i) },
        }
    }
}
}

offset is non-zero when DuckDB writes the results into part of a larger vector. Always add it to the output index.

state_destroy

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct MyState { config_field: i64, accumulator: i64 }
impl AggregateState for MyState {}
unsafe extern "C" fn state_destroy(states: *mut duckdb_aggregate_state, count: idx_t) {
    unsafe { FfiState::<MyState>::destroy_callback(states, count) };
}
}

destroy_callback drops the T in each state whose tag matches (freeing its box, if T is boxed), clearing the tag first, so a second call on the same state is a no-op. See Pitfall L2.

Complex parameter and return types

For functions that accept or return parameterized types like LIST(BIGINT), MAP(VARCHAR, INTEGER), or STRUCT(...), use param_logical and returns_logical instead of param and returns:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct MyState { count: i64 }
impl AggregateState for MyState {}
unsafe extern "C" fn update(_: duckdb_function_info, _: duckdb_data_chunk, _: *mut duckdb_aggregate_state) {}
unsafe extern "C" fn combine(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: *mut duckdb_aggregate_state, _: idx_t) {}
unsafe extern "C" fn finalize(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: duckdb_vector, _: idx_t, _: idx_t) {}
use quack_rs::aggregate::AggregateFunctionBuilder;
use quack_rs::types::{LogicalType, TypeId};

unsafe fn register(con: duckdb_connection) -> Result<(), ExtensionError> {
    unsafe {
        AggregateFunctionBuilder::new("retention")
            .param(TypeId::Boolean)
            .param(TypeId::Boolean)
            .returns_logical(LogicalType::list(TypeId::Boolean))  // LIST(BOOLEAN)
            .ffi_state::<MyState>()                                // state_size + init + destructor
            .update(update)
            .combine(combine)
            .finalize(finalize)
            .register(con)?;
    }
    Ok(())
}
}

param_logical and param can be interleaved — the parameter position is determined by the total number of calls made so far:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
fn demo() {
let _ =
AggregateFunctionBuilder::new("my_func")
    .param(TypeId::Varchar)                          // position 0: VARCHAR
    .param_logical(LogicalType::list(TypeId::BigInt)) // position 1: LIST(BIGINT)
    .param(TypeId::Integer)                           // position 2: INTEGER
    .returns(TypeId::BigInt)
    // ...
;
}
}

If both returns and returns_logical are called, the logical type takes precedence.

Extra info

extra_info attaches arbitrary data to an aggregate function, for example configuration that parameterises its behaviour. DuckDB calls the destroy callback to free the data when the function is dropped:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct MyState { count: i64 }
impl AggregateState for MyState {}
unsafe extern "C" fn update(_: duckdb_function_info, _: duckdb_data_chunk, _: *mut duckdb_aggregate_state) {}
unsafe extern "C" fn combine(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: *mut duckdb_aggregate_state, _: idx_t) {}
unsafe extern "C" fn finalize(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: duckdb_vector, _: idx_t, _: idx_t) {}
unsafe extern "C" fn my_destroy(p: *mut std::os::raw::c_void) {
    drop(unsafe { Box::from_raw(p.cast::<u64>()) });
}
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
use std::os::raw::c_void;

let config = Box::into_raw(Box::new(42u64)).cast::<c_void>();
unsafe {
    AggregateFunctionBuilder::new("my_agg")
        .param(TypeId::BigInt)
        .returns(TypeId::BigInt)
        .extra_info(config, Some(my_destroy))
        .ffi_state::<MyState>()  // state_size + init + destructor
        .update(update)
        .combine(combine)
        .finalize(finalize)
        .register(con)?;
}
Ok(())
}
}

Inside callbacks, retrieve the extra info with AggregateFunctionInfo::get_extra_info().

AggregateFunctionInfo

AggregateFunctionInfo wraps the duckdb_function_info handle that DuckDB passes to every aggregate callback except the destructor. It exposes:

• get_extra_info() -> *mut c_void: the extra-info pointer set at registration.
• set_error(message): fails the current query with message. Called from finalize, it also leaves some states undestroyed; see Known Limitations.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
use quack_rs::aggregate::AggregateFunctionInfo;

unsafe extern "C" fn update(
    info: duckdb_function_info,
    input: duckdb_data_chunk,
    states: *mut duckdb_aggregate_state,
) {
    let info = unsafe { AggregateFunctionInfo::new(info) };
    let extra = unsafe { info.get_extra_info() };
    // ... use extra info, or report errors via info.set_error("...") ...
}
}

Next steps

• State Management — FfiState<T>, AggregateState, and lifecycle details
• Overloading with Function Sets — register multiple signatures under one name

Aggregate State

This page covers aggregate state in a DuckDB aggregate function written in Rust: the AggregateState trait and FfiState<T>, which manages each state's lifecycle (allocation, initialisation, access and destruction) so that you do not write raw-pointer code for it.

Known DuckDB limitation. Every C-API aggregate, and so every aggregate that uses FfiState<T>, reads out of bounds under agg(x) OVER () (whole-partition window frames) and agg(x ORDER BY y). This is a DuckDB C API defect; see Aggregate Functions for the details and DuckDB source lines. Do not use C-API aggregates in those two query shapes.

Reported upstream as duckdb/duckdb#26109.

AggregateState trait

Any type that is Default + Send + Sync + 'static can be used as aggregate state by implementing the AggregateState marker trait. The Sync bound is new in 0.18.0: a window's segment tree lets several threads read the same state as a combine source at once, so a state containing a Cell or RefCell would race. Use atomics or a Mutex instead, or keep that data outside the state.

#![allow(unused)]
fn main() {
use quack_rs::aggregate::AggregateState;

#[derive(Default, Debug)]
struct MyState {
    config: usize,    // set in update, must be propagated in combine
    total: i64,       // accumulated data
}

impl AggregateState for MyState {}
}

AggregateState has no required methods. state_init uses Default to create each fresh state.

FfiState<T>

FfiState<T> names the layout of the bytes DuckDB allocates for each group's state, and the callbacks that manage them. The type itself is never constructed.

A small T, aligned no more strictly than usize and at most 256 bytes, is stored in those bytes directly. A larger or more strictly aligned T is boxed, and the slot holds the pointer. On wasm32, where usize is 4 bytes but u64, i64 and f64 are 8-byte aligned, a state containing one of them is therefore boxed. Either way the slot starts with a tag.

Memory layout

DuckDB-allocated slot (state_size bytes, a multiple of sizeof(usize)):
  [ tag: usize ][ T, padded to whole words ]      T stored inline
  [ tag: usize ][ *mut T ]                        T boxed
                     │
                     └──→  Box<T>  (on the Rust heap)

Storing T inline matters because DuckDB 1.4.4 to 1.5.5 does not destroy every state. When a grouped aggregate's result scan stops early (a LIMIT above it, an error, an interrupt), the states it never reached are never destroyed; so is one state per row of a window frame with EXCLUDE. An inline T's bytes belong to DuckDB, which frees them with the hash table; only what T itself owns on the heap, or a boxed T's box, leaks. See Known Limitations.

The tag marks the slot initialised. When one state_init call fails (a panicking T::default(), say), DuckDB 1.4.4 to 1.5.5 still runs the destructor over every state it created, including states whose state_init never ran, so a slot can hold arbitrary bytes. destroy_callback drops only a slot carrying the tag init_callback wrote, and clears the tag first. The tag is derived from a hash of T's TypeId (and, for a boxed T, the box's address), not from the slot's address, because DuckDB moves states by copying their bytes. The check turns dropping garbage from a certainty into a matter of chance: uninitialised bytes that happen to equal the tag. It mitigates the DuckDB defect (described in the repository's docs/upstream-duckdb-reports.md); it cannot guarantee against it.

Lifecycle callbacks

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::aggregate::{AggregateState, FfiState};
#[derive(Default, Debug)] struct MyState { config: usize, total: i64 }
impl AggregateState for MyState {}
unsafe fn demo(_info: duckdb_function_info, info: duckdb_function_info,
    state: duckdb_aggregate_state, states: *mut duckdb_aggregate_state, count: idx_t) {
// state_size: DuckDB calls this whenever an operator sizes its state buffers
FfiState::<MyState>::size_callback(_info);
// Returns: FfiState::<MyState>::size() (on a 64-bit target, a tag word, then the
// usize and i64 inline)

// state_init: DuckDB calls this for every state slot it allocates, combine
// targets included
FfiState::<MyState>::init_callback(info, state);
// Effect: writes MyState::default() into the slot (or a box holding it), then the tag

// destructor: DuckDB calls this after finalize, on combine's source states once
// merged, and (after a failed state_init) on states never initialised, which
// the tag makes it skip; not on every state (see Known Limitations)
FfiState::<MyState>::destroy_callback(states, count);
// Effect: for each state whose tag matches: clear the tag, then drop the T
}
}

Wiring them up: ffi_state::<T>()

The recommended way to register those three callbacks is ffi_state::<T>() (new in 0.18.0). It installs size_callback, init_callback and destroy_callback for the same T in one call, so the size DuckDB allocates and the state init writes cannot disagree. Wired one by one with the state_size, init and destructor setters, a size callback for one type paired with an init callback for a larger one writes past DuckDB's allocation.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_connection, duckdb_data_chunk,
    duckdb_function_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default, Debug)] struct MyState { config: usize, total: i64 }
impl AggregateState for MyState {}
unsafe extern "C" fn update(_: duckdb_function_info, _: duckdb_data_chunk, _: *mut duckdb_aggregate_state) {}
unsafe extern "C" fn combine(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: *mut duckdb_aggregate_state, _: idx_t) {}
unsafe extern "C" fn finalize(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: duckdb_vector, _: idx_t, _: idx_t) {}
unsafe fn register(con: duckdb_connection) -> Result<(), ExtensionError> {
    unsafe {
        AggregateFunctionBuilder::new("my_agg")
            .param(TypeId::BigInt)
            .returns(TypeId::BigInt)
            .ffi_state::<MyState>()   // state_size + init + destructor
            .update(update)
            .combine(combine)
            .finalize(finalize)
            .register(con)?;
    }
    Ok(())
}
}

AggregateOverloadBuilder has the same method, for each overload of an AggregateFunctionSetBuilder; the set builder itself has none. update, combine and finalize still read the state through FfiState::<T>::with_state / with_state_mut with the same T.

Accessing state in callbacks

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::aggregate::{AggregateState, FfiState};
#[derive(Default, Debug)] struct MyState { config: usize, total: i64 }
impl AggregateState for MyState {}
unsafe fn demo(state_ptr: duckdb_aggregate_state, delta: i64) {
// Immutable access (in finalize, combine source):
if let Some(st) = FfiState::<MyState>::with_state(state_ptr) {
    let value = st.total;
}

// Mutable access (in update, combine target):
if let Some(st) = FfiState::<MyState>::with_state_mut(state_ptr) {
    st.total += delta;
}
}
}

The methods return Option<&T> and Option<&mut T> respectively: None if the slot's tag does not match, which happens after destroy_callback has run or when T::default() panicked in state_init. Returning Option instead of panicking keeps a panic from unwinding across the FFI boundary (Pitfall L3).

The double-free problem — solved

Without quack-rs, a naive destructor looks like:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, idx_t};
struct MyState;
// A hand-written boxed layout: this is the code *without* quack-rs.
#[repr(C)] struct FfiState<T> { inner: *mut T }
// ❌ Naive — causes double-free if DuckDB calls destroy twice
unsafe extern "C" fn destroy(states: *mut duckdb_aggregate_state, count: idx_t) {
    for i in 0..count as usize {
        let ffi = &mut *(*states.add(i) as *mut FfiState<MyState>);
        drop(Box::from_raw(ffi.inner));   // inner is now dangling — crash on second call
    }
}
}

FfiState::destroy_callback clears the slot's tag before dropping the T, and drops only a slot whose tag matches. If DuckDB calls destroy again, the tag no longer matches, the slot is skipped, and with_state returns None.

Testing state logic without DuckDB

AggregateTestHarness<S> simulates the DuckDB aggregate lifecycle in pure Rust:

#![allow(unused)]
fn main() {
use quack_rs::aggregate::AggregateState;
#[derive(Default, Debug)] struct MyState { config: usize, total: i64 }
impl AggregateState for MyState {}
use quack_rs::testing::AggregateTestHarness;

#[test]
fn combine_propagates_config() {
    let mut source = AggregateTestHarness::<MyState>::new();
    source.update(|s| {
        s.config = 5;    // config field set during update
        s.total += 100;
    });

    let mut target = AggregateTestHarness::<MyState>::new();
    target.combine(&source, |src, tgt| {
        tgt.config = src.config;   // must propagate config — Pitfall L1
        tgt.total  += src.total;
    });

    let result = target.finalize();
    assert_eq!(result.config, 5, "config must be propagated in combine");
    assert_eq!(result.total, 100);
}
}

See the Testing Guide for the full test strategy.

Overloading with Function Sets

A DuckDB aggregate function can have several signatures under one name, registered together as a function set. This page shows how to overload an aggregate function in Rust with AggregateFunctionSetBuilder, including variadic aggregates such as retention(c1, c2, ..., c32) and overloads with different return types.

Known DuckDB limitation. C-API aggregates — including every overload in a set — read out of bounds under agg(x) OVER () (whole-partition window frames) and agg(x ORDER BY y). This is a DuckDB C API defect; see Aggregate Functions for the details and DuckDB source lines. Do not use C-API aggregates in those two query shapes.

Reported upstream as duckdb/duckdb#26109.

Note: For scalar function overloads, see ScalarFunctionSetBuilder.

When to use function sets

Use AggregateFunctionSetBuilder when you need:

• Multiple type signatures for the same function name (e.g., my_agg(INT) and my_agg(BIGINT))
• Variadic arity under one name (e.g., retention(2 columns), retention(3 columns), ...)
• Overloads that return different types (see Per-overload return types)

For a single signature, use AggregateFunctionBuilder directly.

Registration

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct RetentionState { hits: u32 }
impl AggregateState for RetentionState {}
unsafe extern "C" fn update(_: duckdb_function_info, _: duckdb_data_chunk, _: *mut duckdb_aggregate_state) {}
unsafe extern "C" fn combine(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: *mut duckdb_aggregate_state, _: idx_t) {}
unsafe extern "C" fn finalize(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: duckdb_vector, _: idx_t, _: idx_t) {}
use quack_rs::aggregate::AggregateFunctionSetBuilder;
use quack_rs::types::TypeId;

unsafe fn register(con: duckdb_connection) -> Result<(), ExtensionError> {
    unsafe {
        AggregateFunctionSetBuilder::new("retention")
            .returns(TypeId::Varchar)
            .overloads(2..=3, |n, builder| {
                // Each overload gets `n` BOOLEAN parameters
                let b = (0..n).fold(builder, |b, _| b.param(TypeId::Boolean));
                b.ffi_state::<RetentionState>() // state_size + init + destructor
                    .update(update)
                    .combine(combine)
                    .finalize(finalize)
            })
            .register(con)?;
    }
    Ok(())
}
}

overloads takes a RangeInclusive<usize> and a closure, called once per arity n with a fresh AggregateOverloadBuilder, that returns the configured overload. The set builder gives every member the set's name when it registers them.

Per-overload return types

DuckDB resolves an aggregate overload from its parameter types and arity alone — the return type plays no part in resolution. Members of one set are therefore free to return different types. This is how DuckDB's own arg_max works:

arg_max(ANY, ANY)      -> ANY
arg_max(ANY, ANY, ANY) -> ANY[]

Set the return type on the overload with AggregateOverloadBuilder::returns (or returns_logical), and add each one with overload:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct IntState { sum: i64 }
impl AggregateState for IntState {}
unsafe extern "C" fn int_update(_: duckdb_function_info, _: duckdb_data_chunk, _: *mut duckdb_aggregate_state) {}
unsafe extern "C" fn int_combine(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: *mut duckdb_aggregate_state, _: idx_t) {}
unsafe extern "C" fn int_finalize(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: duckdb_vector, _: idx_t, _: idx_t) {}
#[derive(Default)] struct StrState { longest: String }
impl AggregateState for StrState {}
unsafe extern "C" fn str_update(_: duckdb_function_info, _: duckdb_data_chunk, _: *mut duckdb_aggregate_state) {}
unsafe extern "C" fn str_combine(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: *mut duckdb_aggregate_state, _: idx_t) {}
unsafe extern "C" fn str_finalize(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: duckdb_vector, _: idx_t, _: idx_t) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
use quack_rs::aggregate::{AggregateFunctionSetBuilder, AggregateOverloadBuilder};
use quack_rs::types::TypeId;

unsafe {
    AggregateFunctionSetBuilder::new("my_agg")
        .overload(
            AggregateOverloadBuilder::new()
                .param(TypeId::Integer)
                .returns(TypeId::Integer)      // my_agg(INTEGER) -> INTEGER
                .ffi_state::<IntState>()
                .update(int_update)
                .combine(int_combine)
                .finalize(int_finalize),
        )
        .overload(
            AggregateOverloadBuilder::new()
                .param(TypeId::Varchar)
                .returns(TypeId::Varchar)      // my_agg(VARCHAR) -> VARCHAR
                .ffi_state::<StrState>()
                .update(str_update)
                .combine(str_combine)
                .finalize(str_finalize),
        )
        .register(con)?;
}
Ok(())
}
}

Each overload carries its own callbacks, so overloads with different parameter types can use different state types: call ffi_state::<T>() on each overload with that overload's state type (AggregateFunctionSetBuilder itself has no ffi_state), and read it in that overload's update, combine and finalize with FfiState::<T>::with_state / with_state_mut for the same T.

Which return type wins

For each overload, in order:

1. AggregateOverloadBuilder::returns_logical
2. AggregateOverloadBuilder::returns
3. AggregateFunctionSetBuilder::returns_logical (the set-level default)
4. AggregateFunctionSetBuilder::returns (the set-level default)

Registration fails, naming the overload index, if an overload reaches the end of that list with nothing set or is missing a required callback. It also fails if two overloads take the same parameter types. All of this is checked for every overload before any DuckDB handle is created.

Other per-overload settings

Each overload can also carry its own extra_info (AggregateOverloadBuilder::extra_info), read in that overload's callbacks with AggregateFunctionInfo::get_extra_info. Ownership works as on AggregateFunctionBuilder: DuckDB frees it once registration has handed it over, even if registration then fails; the builder frees it if it never gets that far.

AggregateOverloadBuilder::null_handling sets an overload's NULL handling.

overload and overloads may be mixed on one builder; overloads register in the order they were added.

Note: AggregateOverloadBuilder was called OverloadBuilder before v0.18.0. The old name is still exported as a deprecated alias at quack_rs::aggregate::builder::OverloadBuilder.

The silent name bug — solved

Pitfall L6: When using a function set, the name must be set on each individual duckdb_aggregate_function via duckdb_aggregate_function_set_name, not just on the set. If any member lacks a name, it is silently not registered — no error is returned.

DuckDB's C API documentation does not mention this. It was found by reading DuckDB's C++ test code at test/api/capi/test_capi_aggregate_functions.cpp. In duckdb-behavioral, 6 of 7 functions failed to register silently due to this bug.

AggregateFunctionSetBuilder::register calls duckdb_aggregate_function_set_name on every member, whether it was added with overload or overloads.

See Pitfall L6.

Complex return types

If all overloads share one complex return type, set it once on the set builder as a default, rather than repeating it on every overload:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct RetentionState { hits: u32 }
impl AggregateState for RetentionState {}
unsafe extern "C" fn update(_: duckdb_function_info, _: duckdb_data_chunk, _: *mut duckdb_aggregate_state) {}
unsafe extern "C" fn combine(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: *mut duckdb_aggregate_state, _: idx_t) {}
unsafe extern "C" fn finalize(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: duckdb_vector, _: idx_t, _: idx_t) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
use quack_rs::aggregate::AggregateFunctionSetBuilder;
use quack_rs::types::{LogicalType, TypeId};

unsafe {
    AggregateFunctionSetBuilder::new("retention")
        .returns_logical(LogicalType::list(TypeId::Boolean))  // default for every overload
        .overloads(2..=32, |n, builder| {
            (0..n).fold(builder, |b, _| b.param(TypeId::Boolean))
                .ffi_state::<RetentionState>()
                .update(update)
                .combine(combine)
                .finalize(finalize)
        })
        .register(con)?;
}
Ok(())
}
}

Individual overloads can also use param_logical for complex parameter types:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
fn demo() {
let _ = AggregateFunctionSetBuilder::new("retention")
.overloads(2..=8, |n, builder| {
    builder
        .param(TypeId::Interval)
        .param_logical(LogicalType::list(TypeId::Timestamp)) // LIST(TIMESTAMP) parameter
        // ...
})
;
}
}

Why not varargs?

DuckDB's C API has no duckdb_aggregate_function_set_varargs. A variadic aggregate must therefore be registered as one overload per supported arity, which overloads does in one call.

Note: Scalar functions do support varargs, through ScalarFunctionBuilder::varargs() (stable C API, no feature flag needed).

Table Functions

A DuckDB table function returns a result set rather than a single value, and is called in the FROM clause: SELECT * FROM my_function(args). This page shows how to write one in Rust with quack-rs. DuckDB drives a table function through three callbacks: bind, init and scan.

quack-rs provides two layers for registering table functions:

1. TypedTableFunctionBuilder<S> (recommended for new extensions) — closure-based API that hides bind/init/scan trampolines behind safe Rust closures and gives every execution a fresh, typed scan state built from what bind produced.
2. TableFunctionBuilder — the underlying raw builder used by TypedTableFunctionBuilder internally. Reach for it when you need fine-grained control: parallel scans (InitInfo::set_max_threads above 1, usually with local_init for per-thread state), projection pushdown with column filtering, or callback shapes that don't fit the "produce state in bind, mutate it in scan" model.

Both builders are backed by the helper types BindInfo, InitInfo, FunctionInfo, FfiBindData<T>, FfiInitData<T>, and FfiLocalInitData<T>.

Lifecycle

DuckDB calls the scan callback repeatedly until it sets the chunk size to 0, which signals the end of the results.

Bind once, init many times. DuckDB keeps the bind data for as long as the bound plan lives and runs init against it on every execution: each EXECUTE of a prepared statement, each iteration of a recursive CTE that references the function. Treat bind data as immutable after bind and build anything a scan consumes (cursors, open files) in init.

Closure-based typed state (with_state)

For the common "take parameters at bind, stream rows until exhausted" pattern, TypedTableFunctionBuilder<S> replaces all three callback trampolines with two closures. With with_state, the state returned by bind is a template: every execution of the plan scans a fresh clone() of it, so S must be Clone + Send.

#![allow(unused)]
fn main() {
use quack_rs::prelude::*;

#[derive(Clone)]
struct State {
    remaining: u64,
}

fn register(reg: &impl Registrar) -> ExtResult<()> {
    let builder = TableFunctionBuilder::new("count_down")
        .param(TypeId::BigInt)
        // 1. bind closure: declare the output schema, read parameters,
        //    return the template scan state (cloned for every execution).
        .with_state::<State, _>(|bind| {
            bind.add_result_column("n", TypeId::BigInt);
            let raw = unsafe { bind.get_parameter_value(0) };
            Ok(State { remaining: raw.as_i64_or(0).max(0) as u64 })
        })
        // 2. scan closure: mutate state, write rows, set chunk size.
        .scan(|state, chunk| {
            if state.remaining == 0 {
                unsafe { chunk.set_size(0) };
                return Ok(());
            }
            let mut writer = unsafe { chunk.writer(0) };
            unsafe { writer.write_i64(0, state.remaining as i64) };
            state.remaining -= 1;
            unsafe { chunk.set_size(1) };
            Ok(())
        })
        .build()?;
    unsafe { reg.register_table(builder) }
}
}

Separate bind data and scan state (with_bind_init)

When the scan state is expensive or impossible to clone (it owns a file handle, a large buffer, a connection), or the parameters and the cursor are naturally separate, use with_bind_init. bind returns immutable bind data B (Send + Sync); init builds a fresh scan state S from &B for every execution:

#![allow(unused)]
fn main() {
use quack_rs::prelude::*;

struct Params { n: i64 }
struct Cursor { next: i64, end: i64 }   // no Clone needed

fn register(reg: &impl Registrar) -> ExtResult<()> {
    let builder = TableFunctionBuilder::new("count_up")
        .param(TypeId::BigInt)
        .with_bind_init(
            |bind| {
                bind.add_result_column("n", TypeId::BigInt);
                let n = unsafe { bind.get_parameter_value(0) }.as_i64_or(0);
                Ok(Params { n })
            },
            |params: &Params| Ok(Cursor { next: 1, end: params.n }),
        )
        .scan(|cursor, chunk| {
            if cursor.next > cursor.end {
                unsafe { chunk.set_size(0) };
                return Ok(());
            }
            unsafe {
                chunk.writer(0).write_i64(0, cursor.next);
                chunk.set_size(1);
            }
            cursor.next += 1;
            Ok(())
        })
        .build()?;
    unsafe { reg.register_table(builder) }
}
}

What you get for free

• No hand-written unsafe extern "C" fn trampolines. TypedTableFunctionBuilder generates them internally.
• Typed scan state. The scan closure receives &mut S, freshly built for each execution (a clone of the with_state template, or init(&B) for with_bind_init) — no manual FfiBindData / FfiInitData shuffling, and a prepared statement can be executed any number of times.
• Panic safety. User closures run inside catch_unwind. A panic is reported as a bind, init or scan error, and the scan sets the chunk size to zero, so the query fails cleanly instead of unwinding across the FFI boundary.
• Error propagation. Return Err(ExtensionError::new("...")) from any closure to report a SQL error to DuckDB.

Trade-offs and threading

• S must be Send + 'static (plus Clone for with_state). Sync is not required, so TypedTableFunctionBuilder forces scans to run on a single worker by calling InitInfo::set_max_threads(1) internally.
• The typed builder does not offer projection pushdown: with pushdown on, the scan's chunk holds only the projected columns and a closure written against the declared schema would write the wrong column. build() returns an error if projection_pushdown(true) was set on the raw builder before with_state / with_bind_init. Use the raw builder for pushdown.
• The bind closure must declare at least one column. With duckdb-1-5, a bind that declares none is reported as an ordinary bind error; DuckDB itself raises an INTERNAL Error with a C++ stack trace for it (and does so for a raw bind callback, which quack-rs cannot check after it returns — call set_error yourself).
• Extensions that need multi-worker parallelism (set_max_threads above 1, with local_init + thread-local buffers) should use the raw TableFunctionBuilder directly.
• TypedTableFunctionBuilder::build() returns a fully configured TableFunctionBuilder, so you can still pass it through any Registrar — including MockRegistrar for unit tests. Registration fails if you then enable projection_pushdown on it or replace its bind, init, local_init, scan or extra_info: the generated callbacks read one another's data.

Builder API

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_bind_info, duckdb_connection, duckdb_data_chunk,
    duckdb_function_info, duckdb_init_info};
unsafe extern "C" fn my_bind_callback(_: duckdb_bind_info) {}
unsafe extern "C" fn my_init_callback(_: duckdb_init_info) {}
unsafe extern "C" fn my_scan_callback(_: duckdb_function_info, _: duckdb_data_chunk) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
use quack_rs::table::{TableFunctionBuilder, BindInfo, FfiBindData, FfiInitData};
use quack_rs::types::TypeId;

TableFunctionBuilder::new("my_function")
    .param(TypeId::BigInt)                 // positional parameter types
    .bind(my_bind_callback)               // declare output columns inside bind
    .init(my_init_callback)
    .scan(my_scan_callback)
    .register(con)?;
Ok(())
}
}

Output columns are declared inside the bind callback using BindInfo::add_result_column, not on the builder itself.

State management

Bind data

Bind data persists from the bind phase through all scan batches — and through every later execution of the same plan (see Bind once, init many times above), possibly read from several threads at once, so FfiBindData::set requires T: Send + Sync. Use FfiBindData<T> to allocate it safely:

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_bind_info;
use quack_rs::table::{BindInfo, FfiBindData};
struct MyBindData {
    limit: i64,
}

unsafe extern "C" fn my_bind(info: duckdb_bind_info) {
    // `get_parameter_value` returns an RAII `Value`; a NULL argument reads as the default.
    let n = unsafe { BindInfo::new(info).get_parameter_value(0) }.as_i64_or(0);
    unsafe { FfiBindData::<MyBindData>::set(info, MyBindData { limit: n }) };
}
}

FfiBindData::set stores the value and registers a destructor so DuckDB frees it at the right time — no Box::into_raw / Box::from_raw needed.

Init (scan) state

Per-scan state (e.g., a current row index) uses FfiInitData<T> (T: Send + Sync, since concurrent scan threads share it):

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_init_info;
use quack_rs::table::FfiInitData;
struct MyScanState {
    pos: i64,
}

unsafe extern "C" fn my_init(info: duckdb_init_info) {
    unsafe { FfiInitData::<MyScanState>::set(info, MyScanState { pos: 0 }) };
}
}

Complete example: generate_series_ext

The hello-ext example registers generate_series_ext(n BIGINT) which emits integers 0 .. n-1. See examples/hello-ext/src/lib.rs for the full source.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_bind_info, duckdb_connection, duckdb_data_chunk,
    duckdb_function_info, duckdb_init_info, DuckDBSuccess};
use quack_rs::data_chunk::DataChunk;
use quack_rs::table::{BindInfo, FfiBindData, FfiInitData, TableFunctionBuilder};
use quack_rs::types::TypeId;
struct GsBindData { total: i64 }
struct GsScanState { pos: i64 }
// Bind: extract `n`, register one output column
unsafe extern "C" fn gs_bind(info: duckdb_bind_info) {
    let bind_info = unsafe { BindInfo::new(info) };
    // Value is RAII — automatically destroyed when dropped.
    // A NULL argument reads as the default rather than aborting.
    let n = unsafe { bind_info.get_parameter_value(0) }.as_i64_or(0);

    bind_info.add_result_column("value", TypeId::BigInt);
    unsafe { FfiBindData::<GsBindData>::set(info, GsBindData { total: n }) };
}

// Init: zero-initialise the scan cursor
unsafe extern "C" fn gs_init(info: duckdb_init_info) {
    unsafe { FfiInitData::<GsScanState>::set(info, GsScanState { pos: 0 }) };
}

// Scan: emit a batch of rows using DataChunk wrapper
unsafe extern "C" fn gs_scan(info: duckdb_function_info, output: duckdb_data_chunk) {
    let chunk = unsafe { DataChunk::from_raw(output) };
    // Never unwrap in a callback: a missing state ends the scan instead.
    let bind = unsafe { FfiBindData::<GsBindData>::get_from_function(info) };
    let state = unsafe { FfiInitData::<GsScanState>::get_mut(info) };
    let (Some(bind), Some(state)) = (bind, state) else {
        unsafe { chunk.set_size(0) };
        return;
    };

    let remaining = bind.total - state.pos;
    let batch = remaining.min(2048).max(0) as usize;

    let mut writer = unsafe { chunk.writer(0) };
    for i in 0..batch {
        unsafe { writer.write_i64(i, state.pos + i as i64) };
    }
    unsafe { chunk.set_size(batch) };
    state.pos += batch as i64;
}
std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
let (mut db, mut con) = (std::ptr::null_mut(), std::ptr::null_mut());
unsafe {
    assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), DuckDBSuccess);
    assert_eq!(libduckdb_sys::duckdb_connect(db, &mut con), DuckDBSuccess);
    TableFunctionBuilder::new("generate_series_ext")
        .param(TypeId::BigInt)
        .bind(gs_bind)
        .init(gs_init)
        .scan(gs_scan)
        .register(con)
        .unwrap();
}
let sum = |sql: &str| -> i64 {
    let mut result = unsafe { quack_rs::query::query(con, sql) }.unwrap();
    let chunk = result.next_chunk().unwrap().unwrap();
    unsafe { chunk.reader(0).read_i64(0) }
};
assert_eq!(sum("SELECT sum(value)::BIGINT FROM generate_series_ext(5)"), 10);
assert_eq!(sum("SELECT count(*) FROM generate_series_ext(5000)"), 5000);
}

Registration

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_bind_info, duckdb_connection, duckdb_data_chunk,
    duckdb_function_info, duckdb_init_info};
use quack_rs::table::TableFunctionBuilder;
use quack_rs::types::TypeId;
unsafe extern "C" fn gs_bind(_: duckdb_bind_info) {}
unsafe extern "C" fn gs_init(_: duckdb_init_info) {}
unsafe extern "C" fn gs_scan(_: duckdb_function_info, _: duckdb_data_chunk) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
TableFunctionBuilder::new("generate_series_ext")
    .param(TypeId::BigInt)
    .bind(gs_bind)
    .init(gs_init)
    .scan(gs_scan)
    .register(con)?;
Ok(())
}
}

Advanced features

Named parameters

Named parameters let callers pass optional arguments by name (e.g., step := 10):

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_bind_info, duckdb_connection, duckdb_data_chunk,
    duckdb_function_info, duckdb_init_info};
use quack_rs::table::TableFunctionBuilder;
use quack_rs::types::TypeId;
unsafe extern "C" fn gs_v2_bind(_: duckdb_bind_info) {}
unsafe extern "C" fn gs_v2_init(_: duckdb_init_info) {}
unsafe extern "C" fn gs_v2_scan(_: duckdb_function_info, _: duckdb_data_chunk) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
TableFunctionBuilder::new("gen_series_v2")
    .param(TypeId::BigInt)                    // positional: n
    .named_param("step", TypeId::BigInt)      // named: step := <value>
    .bind(gs_v2_bind)
    .init(gs_v2_init)
    .scan(gs_v2_scan)
    .register(con)?;
Ok(())
}
}

In the bind callback, read the named parameter with BindInfo::get_named_parameter_value("step"). Named parameters are optional: if the query omits step := …, the returned Value wraps a null handle (is_null() is true), so use a defaulting accessor such as as_i64_or(1).

Registering a name twice

The C API has no table function sets: a second registration under a name that already exists — your own earlier one, another extension's, or a built-in such as range — is dropped by DuckDB while duckdb_register_table_function still reports success, and the old function keeps answering. register therefore checks duckdb_functions() first and returns an error if the name already belongs to a table function or table macro (compared case-insensitively). Table functions registered through the C API live in the in-memory system catalog and are never persisted, so reloading an extension into a database file never trips this check.

Local init (per-thread state)

local_init allocates per-thread state for a scan that runs on several threads. It does not make the scan parallel by itself — that is InitInfo::set_max_threads (see Thread control):

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_bind_info, duckdb_connection, duckdb_data_chunk,
    duckdb_function_info, duckdb_init_info};
use quack_rs::table::TableFunctionBuilder;
use quack_rs::types::TypeId;
unsafe extern "C" fn gs_v2_bind(_: duckdb_bind_info) {}
unsafe extern "C" fn gs_v2_init(_: duckdb_init_info) {}
unsafe extern "C" fn gs_v2_local_init(_: duckdb_init_info) {}
unsafe extern "C" fn gs_v2_scan(_: duckdb_function_info, _: duckdb_data_chunk) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
TableFunctionBuilder::new("gen_series_v2")
    .param(TypeId::BigInt)
    .bind(gs_v2_bind)
    .init(gs_v2_init)
    .local_init(gs_v2_local_init)            // per-thread state allocation
    .scan(gs_v2_scan)
    .register(con)?;
Ok(())
}
}

The local init callback receives duckdb_init_info and can use FfiLocalInitData::<T>::set to store per-thread state (T: Send).

Thread control

Use InitInfo::set_max_threads in the global init callback to tell DuckDB how many threads can scan concurrently. The default is 1. Above 1, DuckDB calls the scan from that many threads at the same time whether or not local_init is set — and all of them share the one global init data and bind data. Do not use FfiInitData::get_mut then; keep shared mutable state behind a Mutex or atomics and read it with FfiInitData::get:

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_init_info;
use quack_rs::table::{FfiInitData, InitInfo};
struct MyState { pos: i64 }
unsafe extern "C" fn gs_v2_init(info: duckdb_init_info) {
    let init_info = unsafe { InitInfo::new(info) };
    init_info.set_max_threads(1);
    unsafe { FfiInitData::<MyState>::set(info, MyState { pos: 0 }) };
}
}

Projection pushdown

Enable projection pushdown to let DuckDB skip unrequested columns:

#![allow(unused)]
fn main() {
use quack_rs::table::TableFunctionBuilder;
fn demo() {
let _ =
TableFunctionBuilder::new("my_func")
    .projection_pushdown(true)
    // ...
;
}
}

Caution: When projection pushdown is enabled, your scan callback must check which columns DuckDB actually needs using InitInfo::projected_column_count and InitInfo::projected_column_index. Writing to non-projected columns causes crashes. projected_column_index returns None past the end of the projection (the C API itself answers 0 there, which is indistinguishable from the first column).

See examples/hello-ext/src/lib.rs for a complete example using named_param, local_init, and set_max_threads.

Complex parameter types

For parameterised types that TypeId cannot express (e.g. LIST(BIGINT), MAP(VARCHAR, INTEGER), STRUCT(...)), use param_logical and named_param_logical:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_bind_info, duckdb_connection, duckdb_data_chunk,
    duckdb_function_info, duckdb_init_info};
use quack_rs::table::TableFunctionBuilder;
use quack_rs::types::TypeId;
unsafe extern "C" fn bind_fn(_: duckdb_bind_info) {}
unsafe extern "C" fn init_fn(_: duckdb_init_info) {}
unsafe extern "C" fn scan_fn(_: duckdb_function_info, _: duckdb_data_chunk) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
use quack_rs::types::LogicalType;

TableFunctionBuilder::new("read_data")
    .param_logical(LogicalType::list(TypeId::Varchar))        // positional LIST param
    .named_param_logical("options", LogicalType::map(          // named MAP param
        TypeId::Varchar, TypeId::Varchar,
    ))
    .bind(bind_fn)
    .init(init_fn)
    .scan(scan_fn)
    .register(con)?;
Ok(())
}
}

BindInfo helpers

BindInfo wraps duckdb_bind_info and exposes these methods:

InitInfo helpers

InitInfo wraps duckdb_init_info:

FunctionInfo helpers

FunctionInfo wraps duckdb_function_info (scan callbacks):

Extra info

Use TableFunctionBuilder::extra_info to attach function-level data that is accessible from all callbacks (bind, init, and scan) via get_extra_info(). The pointee must be Send + Sync: DuckDB passes the same pointer to callbacks running on several threads at once, and frees it on whichever thread releases the function.

Example output

SELECT * FROM generate_series_ext(5);
-- 0
-- 1
-- 2
-- 3
-- 4

SELECT value * value AS sq FROM generate_series_ext(4);
-- 0
-- 1
-- 4
-- 9

See also

• table module documentation
• replacement_scan — for file-path-triggered table scans
• hello-ext README

Replacement Scans

A DuckDB replacement scan lets users query a file by its path alone:

SELECT * FROM 'myfile.myformat'

When DuckDB finds no table with that name, it calls each registered replacement scan in registration order, and one of them can redirect the query to a table function (in the example below, read_myformat('myfile.myformat')). DuckDB's own CSV, Parquet and JSON readers use the same mechanism. This page shows how to register one from a Rust extension with quack-rs.

quack-rs provides ReplacementScanBuilder (a static registration helper) and ReplacementScanInfo (an ergonomic wrapper for callbacks).

Registration API

Unlike the other builders in quack-rs, ReplacementScanBuilder uses a single static call because the DuckDB C API takes all arguments at once:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_database, duckdb_replacement_scan_info};
use std::os::raw::{c_char, c_void};
unsafe extern "C" fn my_scan_callback(_: duckdb_replacement_scan_info, _: *const c_char, _: *mut c_void) {}
fn demo(db: duckdb_database, my_state: String) {
use quack_rs::replacement_scan::ReplacementScanBuilder;

// Low-level: pass raw extra_data and an optional delete callback.
unsafe {
    ReplacementScanBuilder::register(
        db,                            // duckdb_database
        my_scan_callback,              // ReplacementScanFn
        std::ptr::null_mut(),          // extra_data (or a raw pointer)
        None,                          // delete_callback
    );
}

// Ergonomic: pass owned Rust data; boxing and destructor are handled for you.
unsafe {
    ReplacementScanBuilder::register_with_data(db, my_scan_callback, my_state);
}
}
}

Note: Replacement scans are registered on a database handle (duckdb_database), not a connection, and apply to every connection to that database. In an entry point, Connection::register_replacement_scan and register_replacement_scan_with_data do the same through the Connection you are given.

A raw delete_callback must accept a null argument: unlike DuckDB's other destructor slots, it is called with extra_data even when that is null.

Callback signature

The raw callback receives duckdb_replacement_scan_info, but you can wrap it with ReplacementScanInfo for ergonomic, safe access:

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_replacement_scan_info;
use quack_rs::replacement_scan::ReplacementScanInfo;

unsafe extern "C" fn my_scan_callback(
    info: duckdb_replacement_scan_info,
    table_name: *const ::std::os::raw::c_char,
    _data: *mut ::std::os::raw::c_void,
) {
    let path = unsafe { std::ffi::CStr::from_ptr(table_name) }
        .to_str()
        .unwrap_or("");

    if !path.ends_with(".myformat") {
        return; // not ours: DuckDB tries the next replacement scan
    }

    // Use ReplacementScanInfo for ergonomic access
    unsafe {
        ReplacementScanInfo::new(info)
            .set_function("read_myformat")
            .add_varchar_parameter(path);
    }
}
}

table_name is the last part of the table reference: FROM myschema."f.myformat" reaches the callback as f.myformat, so a callback cannot see or honour a schema.

ReplacementScanInfo methods

Data passed to ReplacementScanBuilder::register_with_data must be Send + Sync: it lives in the database-wide configuration, is read by the callback from any connection's thread (concurrently), and is dropped by whichever thread closes the database. The raw register has the same requirement, stated in its # Safety.

When to use replacement scans vs table functions

Most extensions implement both: a table function that does the actual work, and a replacement scan that detects the file extension and transparently routes bare-path queries to the table function.

See also

• replacement_scan module documentation
• Table Functions

Cast Functions

A DuckDB cast function defines how values of one type are converted to another. This page shows how to register one from a Rust extension with quack-rs' CastFunctionBuilder. Once registered, CAST(x AS T) and TRY_CAST(x AS T) use your callback, and so do implicit conversions if you give the cast an implicit cost.

When to use cast functions

• Your extension introduces a new logical type and needs CAST to/from standard types.
• You want to override DuckDB's built-in cast behaviour for a specific type pair.
• You need to control implicit cast priority relative to other registered casts.

Registering a cast

#![allow(unused)]
fn main() {
use quack_rs::cast::{CastFunctionBuilder, CastFunctionInfo, CastMode};
use quack_rs::types::TypeId;
use quack_rs::vector::{VectorReader, VectorWriter};
use libduckdb_sys::{duckdb_function_info, duckdb_vector, idx_t};

unsafe extern "C" fn varchar_to_int(
    info: duckdb_function_info,
    count: idx_t,
    input: duckdb_vector,
    output: duckdb_vector,
) -> bool {
    let cast_info = unsafe { CastFunctionInfo::new(info) };
    let reader = unsafe { VectorReader::from_vector(input, count as usize) };
    let mut writer = unsafe { VectorWriter::new(output) };

    for row in 0..count as usize {
        if !unsafe { reader.is_valid(row) } {
            unsafe { writer.set_null(row) };
            continue;
        }
        let s = unsafe { reader.read_str(row) };
        match s.parse::<i32>() {
            Ok(v) => unsafe { writer.write_i32(row, v) },
            Err(e) => {
                let msg = format!("cannot cast {:?} to INTEGER: {e}", s);
                if cast_info.cast_mode() == CastMode::Try {
                    // TRY_CAST: record a per-row error, which also sets the row to NULL
                    unsafe { cast_info.set_row_error(&msg, row as idx_t, output) };
                } else {
                    // Regular CAST: fail the whole query
                    cast_info.set_error(&msg);
                    return false;
                }
            }
        }
    }
    true
}

fn register(con: libduckdb_sys::duckdb_connection)
    -> Result<(), quack_rs::error::ExtensionError>
{
    unsafe {
        CastFunctionBuilder::new(TypeId::Varchar, TypeId::Integer)
            .function(varchar_to_int)
            .register(con)
    }
}
}

Implicit casts

Provide an implicit_cost to allow DuckDB to use the cast automatically in expressions where the types do not match:

#![allow(unused)]
fn main() {
use quack_rs::cast::CastFunctionBuilder;
use quack_rs::types::TypeId;
use libduckdb_sys::{duckdb_function_info, duckdb_vector, idx_t};
unsafe extern "C" fn my_cast(_: duckdb_function_info, _: idx_t, _: duckdb_vector, _: duckdb_vector) -> bool { true }
fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
unsafe {
    CastFunctionBuilder::new(TypeId::Varchar, TypeId::Integer)
        .function(my_cast)
        .implicit_cost(100) // lower = higher priority
        .register(con)
}
}
}

Extra info

Attach arbitrary data to a cast function using extra_info. This is useful for parameterising the cast behaviour (e.g., a rounding mode):

#![allow(unused)]
fn main() {
use quack_rs::cast::CastFunctionBuilder;
use quack_rs::types::TypeId;
use libduckdb_sys::{duckdb_function_info, duckdb_vector, idx_t};
use std::os::raw::c_void;
unsafe extern "C" fn my_cast(_: duckdb_function_info, _: idx_t, _: duckdb_vector, _: duckdb_vector) -> bool { true }
unsafe extern "C" fn my_destroy(_: *mut c_void) {}
fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
let mode = Box::into_raw(Box::new("round".to_string())).cast::<c_void>();
unsafe {
    CastFunctionBuilder::new(TypeId::Double, TypeId::BigInt)
        .function(my_cast)
        .implicit_cost(100)
        .extra_info(mode, Some(my_destroy))
        .register(con)
}
}
}

Inside the cast callback, retrieve the extra info with CastFunctionInfo::get_extra_info(). The pointee must be Send + Sync: DuckDB passes the same pointer to the callback on every thread that runs the cast, and the destructor runs on whichever thread releases it. CastFunctionBuilder is Send, so an unregistered builder may also run the destructor on the thread that drops it.

If register returns an error — a missing callback or type, a bare composite TypeId (use new_logical), a null connection, or a source or target type that is or contains ANY/INVALID, which DuckDB refuses — the builder still owns the extra info and runs its destructor exactly once. These cases are checked in Rust before DuckDB is called, because duckdb_register_cast_function rejects them before taking ownership of the pointer.

TRY_CAST vs CAST

Inside your callback, check CastFunctionInfo::cast_mode() to distinguish between the two modes:

set_row_error records the message and sets that row of the output to NULL (FlatVector::SetNull inside the C API); row must be less than the callback's count — DuckDB does not check it in release builds.

The return value does nothing in TRY_CAST mode. DuckDB discards it (execute_cast.cpp calls the cast and ignores the result), so returning false does not turn the chunk into NULLs: every row you did not null keeps whatever the output vector held — possibly a previous chunk's value. Null each failed row yourself. The one exception is a panic inside a cast_callback! body: the macro then sets every row of the chunk to NULL, since nothing the body wrote can be trusted.

In Normal mode, set a message before returning false. A cast_callback! body that sets none fails the query with "cast function failed without reporting an error message"; a hand-written extern "C" callback that sets none makes DuckDB report Conversion Error: followed by nothing. An empty message passed to set_error / set_row_error is replaced by a placeholder.

Working example

The examples/hello-ext extension registers two cast functions:

• CAST(VARCHAR AS INTEGER) / TRY_CAST(VARCHAR AS INTEGER) — basic cast
• CAST(DOUBLE AS BIGINT) — with implicit_cost(100) and extra_info for rounding mode

See examples/hello-ext/src/lib.rs for complete, copy-paste-ready references.

Complex source and target types

For casts involving complex types like DECIMAL(18, 3) or LIST(VARCHAR), use the new_logical constructor instead of new:

#![allow(unused)]
fn main() {
use quack_rs::cast::CastFunctionBuilder;
use quack_rs::types::{LogicalType, TypeId};
use libduckdb_sys::{duckdb_function_info, duckdb_vector, idx_t};
unsafe extern "C" fn my_cast(_: duckdb_function_info, _: idx_t, _: duckdb_vector, _: duckdb_vector) -> bool { true }
fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
unsafe {
    CastFunctionBuilder::new_logical(
        LogicalType::list(TypeId::Varchar),   // LIST(VARCHAR) source
        LogicalType::list(TypeId::Integer),   // LIST(INTEGER) target
    )
    .function(my_cast)
    .register(con)
}
}
}

The source() and target() accessor methods return Option<TypeId> — they return None when the type was set via new_logical (since a LogicalType cannot always be expressed as a simple TypeId).

API reference

• CastFunctionBuilder — the builder
• CastFunctionInfo — the info handle inside callbacks
• CastMode — Normal or Try
• cast_callback! — generates a panic-safe cast callback

NULL Handling in Functions

This page explains how NULL inputs reach the scalar and aggregate functions of a DuckDB extension written in Rust, and how to give them SQL NULL semantics.

The one thing to take away: for a scalar function, DefaultNullHandling does not make DuckDB return NULL for you. Your callback is invoked for NULL rows too, and if it writes a value there, that value is the answer. Call DataChunk::propagate_nulls, or use ScalarFunctionBuilder::map1 / map2, which do it for you. An aggregate's update likewise receives NULL rows under either setting.

What DuckDB actually does

DuckDB's FunctionNullHandling has two settings, and quack-rs mirrors them as NullHandling. The names suggest that the default makes the engine handle NULL propagation. For functions registered through the C API it does not: a scalar function's output for a NULL row is kept as written, and an aggregate's update is handed NULL rows (see Aggregate functions). For scalars the result is silent wrong answers rather than an error.

For scalar functions, two pieces of DuckDB source settle it (quoted from v1.5.4):

src/main/capi/scalar_function-c.cpp — the C API bridge calls your callback for the whole flattened chunk and never looks at the result's validity:

void CAPIScalarFunction(DataChunk &input, ExpressionState &state, Vector &result) {
    ...
    input.Flatten();
    ...
    c_bind_info.info.function(c_function_info, c_input, c_result);
    if (!function_info.success) {
        throw InvalidInputException(function_info.error);
    }
    ...
}

src/execution/expression_executor/execute_function.cpp — the only NULL check is a debug-only assertion that your function already did the right thing:

static void VerifyNullHandling(const BoundFunctionExpression &expr, DataChunk &args, Vector &result) {
#ifdef DEBUG
    if (args.data.empty() || expr.function.GetNullHandling() != FunctionNullHandling::DEFAULT_NULL_HANDLING) {
        return;
    }
    // ... D_ASSERT(!result_data.validity.RowIsValid(idx));
#endif
}

Every DuckDB a user installs is a release build, so that assertion is compiled out.

Why the obvious test passes anyway

SELECT my_func(NULL);   -- NULL, even for a broken function

A literal NULL is constant-folded during binding: DuckDB evaluates the expression once, sees a NULL argument to a DEFAULT_NULL_HANDLING function, and substitutes NULL without calling anything. The wrong answers only appear when the argument comes from a column:

CREATE TABLE t(i BIGINT);
INSERT INTO t VALUES (1), (NULL), (3);
SELECT i, my_func(i) FROM t;

Against DuckDB 1.5.4, a function that unconditionally writes 999 returns:

quack-rs pins this behaviour in tests/ffi_roundtrip.rs, so a future DuckDB that starts propagating will show up as a test failure rather than as a surprise.

Doing it right

The safe route: typed scalar functions

ScalarFunctionBuilder::map1 / map2 take an ordinary Rust closure and handle validity for you — a NULL argument short-circuits to a NULL result without ever calling your code:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
fn live_connection() -> libduckdb_sys::duckdb_connection {
    std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
    let (mut db, mut con) = (std::ptr::null_mut(), std::ptr::null_mut());
    unsafe {
        assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), libduckdb_sys::DuckDBSuccess);
        assert_eq!(libduckdb_sys::duckdb_connect(db, &mut con), libduckdb_sys::DuckDBSuccess);
    }
    con
}
/// First column of the first row, as BIGINT; `None` for NULL.
fn query_i64(con: libduckdb_sys::duckdb_connection, sql: &str) -> Option<i64> {
    let mut result = unsafe { quack_rs::query::query(con, sql) }.unwrap();
    let chunk = result.next_chunk().unwrap().unwrap();
    let reader = unsafe { chunk.reader(0) };
    unsafe { reader.is_valid(0).then(|| reader.read_i64(0)) }
}
let con = live_connection();
let run = || -> Result<(), ExtensionError> { unsafe {
ScalarFunctionBuilder::map1("double_it", |x: i64| x * 2)?
    .register(con)?;
} Ok(()) };
run().unwrap();
assert_eq!(query_i64(con, "SELECT double_it(21)"), Some(42));
// From a column, not a literal: `double_it(NULL::BIGINT)` is constant-folded
// to NULL whatever the function does, so it cannot tell a broken one apart.
assert_eq!(query_i64(con, "SELECT double_it(i) FROM (VALUES (NULL::BIGINT)) t(i)"), None);
}

Use map1_opt / map2_opt when the function needs to see NULLs; those register SpecialNullHandling for you and hand the closure Option<T>.

The raw route: propagate_nulls

When you write the extern "C" callback yourself, restore SQL semantics with one call at the end:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
fn live_connection() -> libduckdb_sys::duckdb_connection {
    std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
    let (mut db, mut con) = (std::ptr::null_mut(), std::ptr::null_mut());
    unsafe {
        assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), libduckdb_sys::DuckDBSuccess);
        assert_eq!(libduckdb_sys::duckdb_connect(db, &mut con), libduckdb_sys::DuckDBSuccess);
    }
    con
}
/// First column of the first row, as BIGINT; `None` for NULL.
fn query_i64(con: libduckdb_sys::duckdb_connection, sql: &str) -> Option<i64> {
    let mut result = unsafe { quack_rs::query::query(con, sql) }.unwrap();
    let chunk = result.next_chunk().unwrap().unwrap();
    let reader = unsafe { chunk.reader(0) };
    unsafe { reader.is_valid(0).then(|| reader.read_i64(0)) }
}
quack_rs::scalar_callback!(double_it, |_info, input, output| {
    let chunk = unsafe { DataChunk::from_raw(input) };
    let reader = unsafe { chunk.reader(0) };
    let mut writer = unsafe { VectorWriter::from_vector(output) };
    for row in 0..chunk.size() {
        unsafe { writer.write_i64(row, reader.read_i64(row) * 2) };
    }
    // Without this, double_it(i) for a NULL `i` from a column is 0, not NULL.
    unsafe { chunk.propagate_nulls(&mut writer) };
});
let con = live_connection();
unsafe { ScalarFunctionBuilder::new("double_it").param(TypeId::BigInt).returns(TypeId::BigInt)
    .function(double_it).register(con).unwrap(); }
assert_eq!(query_i64(con, "SELECT double_it(21)"), Some(42));
// From a column, not a literal: `double_it(NULL::BIGINT)` is constant-folded
// to NULL whatever the function does, so it cannot tell a broken one apart.
assert_eq!(query_i64(con, "SELECT double_it(i) FROM (VALUES (NULL::BIGINT)) t(i)"), None);
}

propagate_nulls resolves each column's validity pointer once and marks the output NULL wherever any input column is NULL. A column with no validity mask has no NULLs and costs nothing. DataChunk::any_null(row) is the per-row form when you need the decision inline.

NullHandling enum

#![allow(unused)]
fn main() {
use quack_rs::types::NullHandling;

// Default: the function promises NULL in -> NULL out.
// Scalar: you must keep that promise (see above).
// Aggregate: `update` still receives NULL rows; skip them yourself.
NullHandling::DefaultNullHandling;

// The function means to see NULLs and may return non-NULL for them.
NullHandling::SpecialNullHandling;
}

Aggregate functions

Aggregates behave like scalar functions here: under either setting, update receives every row of the chunk, NULL rows included. CAPIAggregateUpdate in DuckDB's aggregate_function-c.cpp flattens the inputs and passes the whole chunk through; nothing on the way filters by validity. An aggregate that ignores NULLs skips them itself:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe fn demo(chunk: &DataChunk, reader: &VectorReader) {
for row in 0..chunk.size() {
    if !unsafe { reader.is_valid(row) } {
        continue; // a NULL row: its data slot holds no meaningful value
    }
    // ... accumulate reader.read_i64(row) into *states.add(row) ...
}
}
}

SpecialNullHandling declares that the aggregate may return non-NULL for NULL input (a count_with_nulls, say). For an aggregate DuckDB reads the setting in one place only — the correlated-subquery decorrelator, to pick an INNER or LEFT join — and no query we tried (correlated scalar subqueries, with and without arithmetic or coalesce around the aggregate, LATERAL, a correlated subquery in WHERE) answered differently under the two settings on DuckDB 1.5.5. Set it anyway when it is true; it is what DuckDB expects.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
#[derive(Default)] struct CountState { count: i64 }
impl AggregateState for CountState {}
unsafe extern "C" fn my_update(_: duckdb_function_info, _: duckdb_data_chunk, _: *mut duckdb_aggregate_state) {}
unsafe extern "C" fn my_combine(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: *mut duckdb_aggregate_state, _: idx_t) {}
unsafe extern "C" fn my_finalize(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: duckdb_vector, _: idx_t, _: idx_t) {}
unsafe fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
use quack_rs::aggregate::AggregateFunctionBuilder;
use quack_rs::types::{TypeId, NullHandling};

unsafe {
    AggregateFunctionBuilder::new("count_with_nulls")
        .param(TypeId::BigInt)
        .returns(TypeId::BigInt)
        .null_handling(NullHandling::SpecialNullHandling)
        .ffi_state::<CountState>()
        .update(my_update)   // counts rows whose value is NULL, too
        .combine(my_combine)
        .finalize(my_finalize)
        .register(con)?;
}
Ok(())
}
}

Empty groups in a correlated subquery

One difference from an uncorrelated query holds under both settings. In SELECT (SELECT my_count(x) FROM t2 WHERE t2.k = t1.k) FROM t1, an outer row with no matching t2 rows gets NULL: the decorrelated plan joins the aggregate's groups back to the outer rows, and an outer row with no group never has an empty state finalized. DuckDB rewrites that NULL to 0 for its own count and count(*) only. A count-like aggregate of yours that returns 0 for empty input therefore returns NULL here; write coalesce((SELECT ...), 0) if the query needs 0. (SELECT my_count(x) FROM t2 WHERE false, uncorrelated, does finalize an empty state and returns 0.)

When to use special NULL handling

If you don't call .null_handling(), DefaultNullHandling is used.

SQL Macros

A DuckDB SQL macro packages a SQL expression or query as a named function, with no FFI callback behind it. This page shows how to create scalar and table macros from a Rust extension with quack-rs' SqlMacro: you give the macro body as a string and call .register(con), which runs CREATE OR REPLACE MACRO.

Two macro types

Scalar macros

A scalar macro wraps a SQL expression. Think of it as a parameterized SQL alias:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_connection, DuckDBSuccess};
use quack_rs::error::ExtensionError;
fn live_connection() -> duckdb_connection {
    std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
    let (mut db, mut con) = (std::ptr::null_mut(), std::ptr::null_mut());
    unsafe {
        assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), DuckDBSuccess);
        assert_eq!(libduckdb_sys::duckdb_connect(db, &mut con), DuckDBSuccess);
    }
    con
}
fn query_i64(con: duckdb_connection, sql: &str) -> i64 {
    let mut result = unsafe { quack_rs::query::query(con, sql) }.unwrap();
    let chunk = result.next_chunk().unwrap().unwrap();
    unsafe { chunk.reader(0).read_i64(0) }
}
use quack_rs::sql_macro::SqlMacro;

fn register(con: duckdb_connection) -> Result<(), ExtensionError> {
    unsafe {
        // clamp(x, lo, hi) → greatest(lo, least(hi, x))
        SqlMacro::scalar("clamp", &["x", "lo", "hi"], "greatest(lo, least(hi, x))")?
            .register(con)?;

        // golden_ratio() → 1.61803398874989
        SqlMacro::scalar("golden_ratio", &[], "1.61803398874989")?
            .register(con)?;

        // safe_div(a, b) → CASE WHEN b = 0 THEN NULL ELSE a / b END
        SqlMacro::scalar(
            "safe_div",
            &["a", "b"],
            "CASE WHEN b = 0 THEN NULL ELSE a / b END",
        )?
        .register(con)?;
    }
    Ok(())
}
let con = live_connection();
register(con).unwrap();
assert_eq!(query_i64(con, "SELECT clamp(9, 1, 5)::BIGINT"), 5);
assert_eq!(query_i64(con, "SELECT clamp(-3, 1, 5)::BIGINT"), 1);
assert_eq!(query_i64(con, "SELECT (golden_ratio() * 1000)::BIGINT"), 1618);
assert_eq!(query_i64(con, "SELECT count(*) FROM (SELECT safe_div(1, 0) AS v) WHERE v IS NULL"), 1);
}

Use in DuckDB:

SELECT clamp(rating, 1, 5) FROM reviews;
SELECT safe_div(revenue, orders) FROM monthly_stats;

Table macros

A table macro wraps a SQL query that returns rows:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_connection, DuckDBSuccess};
use quack_rs::error::ExtensionError;
use quack_rs::sql_macro::SqlMacro;
fn live_connection() -> duckdb_connection {
    std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
    let (mut db, mut con) = (std::ptr::null_mut(), std::ptr::null_mut());
    unsafe {
        assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), DuckDBSuccess);
        assert_eq!(libduckdb_sys::duckdb_connect(db, &mut con), DuckDBSuccess);
    }
    con
}
fn query_i64(con: duckdb_connection, sql: &str) -> i64 {
    let mut result = unsafe { quack_rs::query::query(con, sql) }.unwrap();
    let chunk = result.next_chunk().unwrap().unwrap();
    unsafe { chunk.reader(0).read_i64(0) }
}
fn register(con: duckdb_connection) -> Result<(), ExtensionError> {
unsafe {
    // active_users(tbl) → SELECT * FROM query_table(tbl) WHERE active = true
    SqlMacro::table(
        "active_users",
        &["tbl"],
        "SELECT * FROM query_table(tbl) WHERE active = true",
    )?
    .register(con)?;

    // recent_orders(days) → last N days of orders
    SqlMacro::table(
        "recent_orders",
        &["days"],
        "SELECT * FROM orders WHERE order_date >= current_date - INTERVAL (days) DAY",
    )?
    .register(con)?;
}
Ok(())
}
let con = live_connection();
unsafe { quack_rs::query::execute(con, "CREATE TABLE users AS SELECT * FROM (VALUES (1, true), (2, false), (3, true)) t(id, active)") }.unwrap();
unsafe { quack_rs::query::execute(con, "CREATE TABLE orders AS SELECT current_date - 3 AS order_date UNION ALL SELECT current_date - 30") }.unwrap();
register(con).unwrap();
assert_eq!(query_i64(con, "SELECT count(*) FROM recent_orders(7)"), 1);
assert_eq!(query_i64(con, "SELECT count(*) FROM active_users(users)"), 2);
}

A table macro's body is bound when the macro is created, so every table it names directly (orders above) must already exist when register runs, or registration fails with a catalog error. To take a table as a parameter, read it through query_table(tbl): a bare FROM tbl looks for a table literally named tbl.

Use in DuckDB:

SELECT * FROM active_users(users);
SELECT count(*) FROM recent_orders(7);

Inspecting the generated SQL

to_sql() returns the CREATE OR REPLACE MACRO statement without requiring a live connection. Use it for logging, debugging, or assertions in tests:

#![allow(unused)]
fn main() {
use quack_rs::sql_macro::SqlMacro;
let m = SqlMacro::scalar("add", &["a", "b"], "a + b")?;
assert_eq!(
    m.to_sql(),
    r#"CREATE OR REPLACE MACRO "add"("a", "b") AS (a + b)"#
);

let t = SqlMacro::table("active_users", &["tbl"], "SELECT * FROM query_table(tbl) WHERE active = true")?;
assert_eq!(
    t.to_sql(),
    r#"CREATE OR REPLACE MACRO "active_users"("tbl") AS TABLE SELECT * FROM query_table(tbl) WHERE active = true"#
);
Ok::<(), quack_rs::error::ExtensionError>(())
}

Name and parameter validation

Macro names are validated with validate_function_name, the same rules as function names, and parameter names with validate_parameter_name. A name must:

• start with an ASCII letter or underscore, followed by ASCII letters, digits or underscores;
• be at most 256 characters long;
• not be a DuckDB keyword that cannot be used in that position unquoted. For a macro, that is a keyword it cannot be called by (order, coalesce); for a parameter, one the body cannot refer to it by (order, left). The two lists differ: a parameter may be called columns, which a macro may not.

Case is not restricted — DuckDB identifiers are case-insensitive, so a macro registered as MyMacro is callable as mymacro(...) or MYMACRO(...).

#![allow(unused)]
fn main() {
use quack_rs::sql_macro::SqlMacro;
assert!(SqlMacro::scalar("1f", &[], "1").is_err());       // ❌ starts with a digit
assert!(SqlMacro::scalar("my-macro", &[], "1").is_err()); // ❌ hyphen
assert!(SqlMacro::scalar("f", &["a b"], "1").is_err());   // ❌ space in param
assert!(SqlMacro::scalar("f", &["order"], "1").is_err()); // ❌ reserved keyword as param
assert!(SqlMacro::scalar("f", &["left"], "1").is_err());  // ❌ a body cannot refer to it
assert!(SqlMacro::scalar("columns", &[], "1").is_err());  // ❌ cannot be called as a macro
assert!(SqlMacro::scalar("f", &["columns"], "1").is_ok()); // ✅ fine as a parameter
assert!(SqlMacro::scalar("MyMacro", &[], "1").is_ok());   // ✅ mixed case allowed
assert!(SqlMacro::scalar("f", &["X"], "1").is_ok());      // ✅ mixed-case param allowed
assert!(SqlMacro::scalar("f", &["_x"], "1").is_ok());     // ✅ underscore prefix allowed
}

SQL injection safety

Macro and parameter names are restricted to ASCII letters, digits and underscores, preventing SQL injection at the identifier level. to_sql() additionally emits every name as a double-quoted identifier ("name") — the validated character set cannot contain ", so no escaping is needed. Quoting does not make names case-sensitive in DuckDB.

The body (expression or query) is your own extension code — it is included verbatim. Never build macro bodies from untrusted user input. register does refuse a body that turns the statement into several (1); DROP TABLE t; SELECT (1) — it counts statements with DuckDB's own parser (duckdb_extract_statements) and executes nothing if there is more than one — but a body can still change the meaning of the single statement it is part of.

A scalar body containing -- gets a newline before the closing parenthesis, so a trailing line comment ("x + 1 -- plus one") does not comment it out.

Where a macro lives

A macro is not a function registration: register runs CREATE OR REPLACE MACRO, so the macro is an ordinary catalog object in the connection's default database and schema — the user's database:

• It persists. In a database file the macro is still there in the next session, even if the extension is never loaded again. Reloading is fine: OR REPLACE replaces it.
• It needs a writable database. On a read-only database the CREATE fails; an entry point that propagates that error with ? makes LOAD fail. Decide whether a macro is essential there.
• It silently replaces a user's macro of the same name. Prefix macro names with your extension's name.
• It can shadow a built-in. A macro named abs in the default schema is found before the built-in abs, so abs(-1) calls the macro.

How it works under the hood

SqlMacro::register counts the statements in to_sql() with duckdb_extract_statements, refuses more than one, and executes the CREATE OR REPLACE MACRO statement via duckdb_query.

The query result is zero-initialized before duckdb_query, any error message is read with duckdb_result_error, and duckdb_destroy_result runs on success and failure alike.

Choosing between macros and scalar functions

Copy Functions

A DuckDB copy function implements a custom file format for the COPY statement. This page shows how to register one from a Rust extension with quack-rs' CopyFunctionBuilder.

Requires the duckdb-1-5 feature flag (DuckDB 1.5.0+).

A format can support writing, reading, or both:

duckdb_register_copy_function decides which directions a format supports by looking at the sink and the reader independently, so a read-only format leaves the writing callbacks unset entirely. Set bind, sink and finalize together or not at all: register refuses a builder with only some of them, and one that implements neither direction.

Lifecycle (COPY … TO)

1. Bind — called when the statement is bound: once for a plain COPY, and again on every EXECUTE of a prepared one. Inspect output columns, configure the export.
2. Global init — called once per output file: once for a plain COPY, once per file with PER_THREAD_OUTPUT or PARTITION_BY. Open the file, allocate that file's global state. With USE_TMP_FILE the path is a temporary name that DuckDB renames afterwards.
3. Sink — called for each data chunk; with PER_THREAD_OUTPUT or PARTITION_BY, from several threads at once (see Threads). Write rows to the output.
4. Finalize — called once per output file, after its last sink. Flush buffers, close the file. It is not called when a sink reports an error, so release resources in the global state's destructor as well.

Builder API

#![allow(unused)]
fn main() {
use quack_rs::copy_function::CopyFunctionBuilder;

fn demo(
    my_bind_fn: quack_rs::copy_function::CopyBindFn,
    my_global_init_fn: quack_rs::copy_function::CopyGlobalInitFn,
    my_sink_fn: quack_rs::copy_function::CopySinkFn,
    my_finalize_fn: quack_rs::copy_function::CopyFinalizeFn,
) -> Result<(), quack_rs::error::ExtensionError> {
let builder = CopyFunctionBuilder::try_new("my_format")?
    .bind(my_bind_fn)
    .global_init(my_global_init_fn)
    .sink(my_sink_fn)
    .finalize(my_finalize_fn);

// Register on a connection, for example in the entry point:
// unsafe { builder.register(con)?; }
Ok(())
}
}

COPY … FROM

Reading is a table function, attached to the copy function rather than registered on its own. Build it with TableFunctionBuilder::build_handle, then hand it to copy_from:

#![allow(unused)]
fn main() {
use quack_rs::copy_function::CopyFunctionBuilder;
use quack_rs::table::TableFunctionBuilder;
use quack_rs::types::TypeId;

fn demo(
    bind: quack_rs::table::BindFn,
    init: quack_rs::table::InitFn,
    scan: quack_rs::table::ScanFn,
) -> Result<(), quack_rs::error::ExtensionError> {
// SAFETY: the callbacks match their declared signatures.
let reader = unsafe {
    TableFunctionBuilder::new("my_format")   // name it after the format
        .param(TypeId::Varchar)              // the file path — exactly one
        .named_param("skip_rows", TypeId::BigInt) // a COPY option
        .bind(bind)
        .init(init)
        .scan(scan)
        .build_handle()
}?;

let format = CopyFunctionBuilder::try_new("my_format")?.copy_from(reader)?;
// unsafe { format.register(con)?; }
Ok(())
}
}

Four things about the reader are not like an ordinary table function:

• The file path is positional parameter 0, always VARCHAR. duckdb.h requires the function to declare exactly that one parameter, and DuckDB does not check it — copy_from does, and returns an error naming the mismatch.
• COPY options are named parameters. (FORMAT my_format, SKIP_ROWS 1) arrives as skip_rows; matching is case-insensitive. An option the function never declared is a binder error before your bind callback runs — and the message names the table function, which is why the example gives it the format's name.
• Those options arrive uncast. DuckDB passes each value as written, not cast to the declared type: SKIP_ROWS 'abc' reaches a BIGINT parameter as the VARCHAR 'abc', and SKIP_ROWS 3 as an INTEGER. An option written without a value ((FORMAT my_format, HEADER)) is not passed at all. Check Value::type_id() before trusting a value — as_i64_or(0) on 'abc' quietly returns the default.
• The schema is already fixed, because COPY … FROM loads into an existing table. The bind callback must not call add_result_column (a typed reader built with with_state or with_bind_init fails its bind if it does). Read the target's schema instead:

#![allow(unused)]
fn main() {
use quack_rs::table::BindInfo;
fn demo(bind: &BindInfo) {
for i in 0..bind.result_column_count() {
    let name = bind.result_column_name(i);
    // SAFETY: `i` is in range, and this runs during the bind callback.
    let ty = unsafe { bind.result_column_type(i) };
    let _ = (name, ty);
}
}
}

Registering a format name twice

duckdb_register_copy_function drops a copy function whose name already exists — your earlier registration, another extension's, or a built-in format such as csv — and still reports success. register checks first and returns an error. There is no catalog view of copy functions, so the check asks the binder: it runs COPY (SELECT <missing column>) TO '' (FORMAT '<name>'), where a binder error means the format resolved and a catalog error means it did not. Nothing is written and no copy callback runs; a format name owned by an autoloadable extension (parquet, json) may be autoloaded by that lookup, exactly as the same COPY typed by a user would. Copy functions registered through the C API are never persisted, so reloading into a database file does not trip the check.

Options

CopyBindInfo::options() returns the COPY … TO options as one STRUCT value (None only if DuckDB returns a null handle). How DuckDB 1.5.5 builds it:

• Option names are upper-cased: compression 'zstd' arrives as COMPRESSION. FORMAT itself is not among them.
• With no options besides FORMAT, the value is SQL NULL, not an empty STRUCT — check is_sql_null() first.
• An option given without a value (HEADER) is a NULL field.
• Several values (LST (1, 2)) arrive as a LIST, or an unnamed STRUCT when their types differ.
• An explicit NULL value is rejected by the binder before your callback runs.
• Field order follows DuckDB's internal hash map, not the statement — look fields up by name:

#![allow(unused)]
fn main() {
use quack_rs::copy_function::CopyBindInfo;
fn demo(bind: &CopyBindInfo) -> Option<String> {
let options = bind.options()?;
if options.is_sql_null() {
    return None; // COPY ... (FORMAT my_format) with no other options
}
let names = options.struct_field_names();
let idx = names.iter().position(|n| n == "COMPRESSION")?;
options.struct_child(idx)?.as_str().ok()
}
}

Threads

The data pointers are untyped, so the compiler cannot check this for you:

• extra_info lives as long as the database and is read from every connection's thread — treat it as T: Send + Sync.
• Bind data is shared by every sink call. COPY … TO with PER_THREAD_OUTPUT or PARTITION_BY runs the sink on several threads at once — treat it as T: Send + Sync and never mutate it without a lock.
• Global state is one per output file: per thread with PER_THREAD_OUTPUT, per partition with PARTITION_BY (reachable from more than one thread). Guard any mutation with a Mutex unless you know neither option is in use.

Callback signatures

Callback info wrappers

Each phase provides an ergonomic wrapper type around its raw info handle. Wrap the handle at the top of your callback to access helper methods:

CopyBindInfo

CopyGlobalInitInfo

CopySinkInfo

CopyFinalizeInfo

All four wrappers are re-exported from quack_rs::copy_function:

#![allow(unused)]
fn main() {
use quack_rs::copy_function::{CopyBindInfo, CopyGlobalInitInfo, CopySinkInfo, CopyFinalizeInfo};
}

Related modules

• config_option — register custom settings for your format
• client_context — access the file system and catalog from callbacks
• table_description — inspect table metadata
• catalog — look up catalog entries
• table — build the table function a COPY … FROM needs

Reading & Writing Vectors

DuckDB passes data to and from your extension as vectors: columnar arrays of typed values, each with a separate validity (NULL) bitmap. VectorReader and VectorWriter give typed access to these vectors from scalar, aggregate and table function callbacks; DataChunk, StructReader, StructWriter and ChunkWriter build on them.

VectorReader

Construction

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_data_chunk, duckdb_function_info, duckdb_vector};
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(input: duckdb_data_chunk, column_index: usize) {
// In a scalar function callback:
let reader = unsafe { VectorReader::new(input, column_index) };

// In an aggregate update callback:
let reader = unsafe { VectorReader::new(input, 0) };   // first column
}
}

VectorReader::new takes the duckdb_data_chunk and a zero-based column index. The reader holds raw pointers into the chunk, so it must not outlive the callback.

Row count

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(reader: &VectorReader) {
let n = reader.row_count();   // number of rows in this chunk
}
}

Chunk sizes vary. Always loop over 0..reader.row_count(); never assume a fixed size.

NULL check

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(reader: &VectorReader, writer: &mut VectorWriter) {
for row in 0..reader.row_count() {
if unsafe { !reader.is_valid(row) } {
    // row is NULL — skip or propagate NULL to output
    unsafe { writer.set_null(row) };
    continue;
}
}
}
}

Always check is_valid before reading. Reading a fixed-width value from a NULL row returns garbage data; reading a VARCHAR or BLOB from one can follow a stale pointer into freed memory (see NULL Handling & Strings).

Reading values

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(reader: &VectorReader, row: usize) {
let i: i8  = unsafe { reader.read_i8(row) };
let i: i16 = unsafe { reader.read_i16(row) };
let i: i32 = unsafe { reader.read_i32(row) };
let i: i64 = unsafe { reader.read_i64(row) };
let u: u8  = unsafe { reader.read_u8(row) };
let u: u16 = unsafe { reader.read_u16(row) };
let u: u32 = unsafe { reader.read_u32(row) };
let u: u64 = unsafe { reader.read_u64(row) };
let f: f32 = unsafe { reader.read_f32(row) };
let f: f64 = unsafe { reader.read_f64(row) };
let b: bool = unsafe { reader.read_bool(row) };   // safe: uses u8 != 0
let s: &str = unsafe { reader.read_str(row) };    // handles inline + pointer format
let iv = unsafe { reader.read_interval(row) };    // returns DuckInterval

// Temporal and binary types (v0.10.0+):
let d: i32 = unsafe { reader.read_date(row) };      // days since epoch
let ts: i64 = unsafe { reader.read_timestamp(row) }; // microseconds since epoch
let t: i64 = unsafe { reader.read_time(row) };       // microseconds since midnight
let blob: &[u8] = unsafe { reader.read_blob(row) };  // binary data
let uuid: u128 = unsafe { reader.read_uuid(row) };   // UUID's textual 128 bits
}
}

VectorWriter

Construction

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_data_chunk, duckdb_function_info, duckdb_vector};
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(output: duckdb_vector, result: duckdb_vector) {
// In a scalar function callback:
let mut writer = unsafe { VectorWriter::new(output) };

// In an aggregate finalize callback:
let mut writer = unsafe { VectorWriter::new(result) };
}
}

Writing values

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
use quack_rs::interval::DuckInterval;
fn demo(writer: &mut VectorWriter, row: usize, s: &str, interval: DuckInterval,
    days_since_epoch: i32, micros_since_epoch: i64, micros_since_midnight: i64,
    bytes: Vec<u8>, uuid_bits: u128) {
unsafe { writer.write_i8(row, -8) };
unsafe { writer.write_i16(row, -16) };
unsafe { writer.write_i32(row, -32) };
unsafe { writer.write_i64(row, -64) };
unsafe { writer.write_u8(row, 8) };
unsafe { writer.write_u16(row, 16) };
unsafe { writer.write_u32(row, 32) };
unsafe { writer.write_u64(row, 64) };
unsafe { writer.write_f32(row, 3.5) };
unsafe { writer.write_f64(row, 2.5) };
unsafe { writer.write_bool(row, true) };
unsafe { writer.write_varchar(row, s) };   // &str
unsafe { writer.write_str(row, s) };       // alias for write_varchar
unsafe { writer.write_interval(row, interval) };  // DuckInterval

// Temporal and binary types (v0.10.0+):
unsafe { writer.write_date(row, days_since_epoch) };
unsafe { writer.write_timestamp(row, micros_since_epoch) };
unsafe { writer.write_time(row, micros_since_midnight) };
unsafe { writer.write_blob(row, &bytes) };
unsafe { writer.write_uuid(row, uuid_bits) };        // UUID's textual 128 bits
}
}

write_varchar and write_blob panic for a value longer than vector::string::MAX_STRING_LEN (u32::MAX bytes, DuckDB's string length limit) rather than store a truncated one. Inside scalar_callback! and the typed scalar constructors the panic becomes a SQL error. To handle the error yourself, use try_write_varchar / try_write_blob, which return Result<(), ExtensionError> and write nothing on error.

UUID is not stored as you'd expect

A UUID column is physically a HUGEINT, but the 128 bits in the vector are not the bits you see in the text form: DuckDB flips the top bit so that comparing the signed integers orders UUIDs the same way comparing their strings does.

SELECT '11111111-2222-3333-4444-555555555555'::UUID
  read_i128 (raw storage) : 0x91111111222233334444555555555555
  read_uuid (textual bits): 0x11111111222233334444555555555555

read_uuid / write_uuid apply the flip for you and speak in textual bits (u128) — the same convention as Value::uuid / Value::as_uuid and every Rust Uuid type. Reach for read_i128 / write_i128 only when you want the raw storage, and use quack_rs::vector::{uuid_from_storage, uuid_to_storage} to convert.

Writing NULL

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(writer: &mut VectorWriter, row: usize) {
unsafe { writer.set_null(row) };
}
}

Pitfall L4: set_null calls duckdb_vector_ensure_validity_writable automatically before duckdb_vector_get_validity. A vector with no NULLs yet usually has no validity mask, so without that call get_validity returns NULL and duckdb_validity_set_row_invalid silently does nothing — the row you meant to be NULL reads back as a valid value. VectorWriter::set_null handles this correctly. See Pitfall L4.

NULL rows of STRUCT and ARRAY outputs

For a STRUCT output, set_null(row) (and set_null_range, and DataChunk::propagate_nulls, which uses it) also nulls that row in every field, recursively; for an ARRAY of size n it nulls child rows row * n .. row * n + n. This mirrors DuckDB's internal FlatVector::SetNull, and it matters: struct_extract / s.a reads the field vector without looking at the parent, so a NULL struct row whose fields were left valid returns the stale field value. StructWriter::set_row_null(row) does the same from a StructWriter. LIST / MAP elements are not touched (as in DuckDB).

To reuse such a row, call set_valid(row) first: on a row that is NULL it also marks valid everything set_null nulled below it. Then write the fields, and any field NULLs after that. On a row that is already valid, set_valid leaves the fields alone, so marking a row valid after writing its fields keeps their NULLs.

Clearing NULL (v0.11.0+)

To undo a previous set_null call and mark a row as valid again:

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(writer: &mut VectorWriter, row: usize) {
unsafe { writer.set_valid(row) };
}
}

Like set_null, set_valid calls ensure_validity_writable first.

DataChunk

DataChunk wraps a duckdb_data_chunk handle and gives access to its vectors and row count without raw FFI calls:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_data_chunk, duckdb_function_info, duckdb_vector};
use quack_rs::data_chunk::DataChunk;

unsafe extern "C" fn my_scan(info: duckdb_function_info, output: duckdb_data_chunk) {
    let chunk = unsafe { DataChunk::from_raw(output) };
    let mut writer = unsafe { chunk.writer(0) };    // VectorWriter for column 0
    unsafe { writer.write_i64(0, 42) };
    unsafe { chunk.set_size(1) };                   // set output row count
}
}

Methods:

• size() — current row count
• set_size(n) — set row count (0 = end of stream)
• column_count() — number of columns
• vector(col) — raw duckdb_vector handle
• writer(col) — VectorWriter for a column
• reader(col) — VectorReader for a column
• struct_writer(col, field_count) — StructWriter for a STRUCT output column
• struct_reader(col, field_count) — StructReader for a STRUCT input column
• struct_field_reader(col, field) — VectorReader for a specific STRUCT field
• any_null(row) — whether any column is NULL at row
• propagate_nulls(&mut writer) — mark each output row NULL where any input column is NULL
• into_chunk_writer() — convert to ChunkWriter, which calls set_size on drop

StructWriter / StructReader

For STRUCT columns, creating a VectorWriter or VectorReader for each field by hand is verbose. StructWriter and StructReader create one per field at construction:

#![allow(unused)]
fn main() {
use quack_rs::data_chunk::DataChunk;
struct Output { success: bool, data: String, count: i64, day: i32, payload: Vec<u8> }
fn demo(chunk: &DataChunk, row: usize, result: &Output) {
// Writing a 5-field STRUCT output:
let mut sw = unsafe { chunk.struct_writer(0, 5) };
unsafe {
    sw.write_bool(row, 0, result.success);
    sw.write_varchar(row, 1, &result.data);
    sw.write_i64(row, 2, result.count);
    sw.write_date(row, 3, result.day);
    sw.write_blob(row, 4, &result.payload);
}

// Reading a 3-field STRUCT input:
let sr = unsafe { chunk.struct_reader(0, 3) };
for row in 0..chunk.size() {
    let name = unsafe { sr.read_str(row, 0) };
    let age = unsafe { sr.read_i32(row, 1) };
    let active = unsafe { sr.read_bool(row, 2) };
}
}
}

ChunkWriter

ChunkWriter wraps an output duckdb_data_chunk and counts the rows handed out by next_row. It calls set_size with that count on drop, so the row count cannot be forgotten or set wrongly. next_row returns None once the chunk holds duckdb_vector_size() rows:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_data_chunk, duckdb_function_info, duckdb_vector};
use quack_rs::data_chunk::DataChunk;
struct Item { name: String, value: i64 }
fn demo(output: duckdb_data_chunk, data: &[Item]) {
let mut cw = unsafe { DataChunk::from_raw(output).into_chunk_writer() };
for item in data {
    let Some(row) = cw.next_row() else { break };   // chunk is full
    unsafe { cw.writer(0).write_varchar(row, &item.name) };
    unsafe { cw.writer(1).write_i64(row, item.value) };
}
// set_size called automatically when `cw` is dropped
}
}

ValidityBitmap

For advanced NULL handling beyond VectorWriter::set_null, use ValidityBitmap directly:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_data_chunk, duckdb_function_info, duckdb_vector};
fn demo(some_vector: duckdb_vector, row: usize) {
use quack_rs::vector::ValidityBitmap;

// Writing NULLs:
let mut bitmap = unsafe { ValidityBitmap::ensure_writable(some_vector) };
unsafe { bitmap.set_row_invalid(row as u64) };   // mark as NULL
unsafe { bitmap.set_row_valid(row as u64) };     // mark as non-NULL

// Reading NULLs:
let bitmap = unsafe { ValidityBitmap::get_read_only(some_vector) };
let is_valid = unsafe { bitmap.row_is_valid(row as u64) };
}
}

ValidityBitmap is available in the prelude: use quack_rs::prelude::*.

Utility functions

The quack_rs::vector module provides two utility functions:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_data_chunk, duckdb_function_info, duckdb_vector};
fn demo(some_vector: duckdb_vector) {
use quack_rs::vector::{vector_size, vector_get_column_type};

// Rows per data chunk: 2048 unless DuckDB was built with another STANDARD_VECTOR_SIZE.
let size: u64 = vector_size();

// Returns the LogicalType of a vector (unsafe — requires a valid duckdb_vector).
let lt = unsafe { vector_get_column_type(some_vector) };
}
}

Memory layout details

DuckDB stores vector data as flat arrays. VectorReader and VectorWriter compute element addresses as base_ptr + row * stride:

[value0][value1][value2]...[valueN]   ← typed array
[validity bitmap]                      ← separate bit array, 1 bit per row

The validity bitmap is lazily allocated — it may be null if no NULLs have been written. This is why duckdb_vector_ensure_validity_writable must be called before duckdb_vector_get_validity when writing NULLs; VectorWriter and ValidityBitmap::ensure_writable do so.

Complete scalar function pattern

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_data_chunk, duckdb_function_info, duckdb_vector};
use quack_rs::vector::{VectorReader, VectorWriter};
fn transform(v: i64) -> i64 { v }
unsafe extern "C" fn my_scalar(
    _info: duckdb_function_info,
    input: duckdb_data_chunk,
    output: duckdb_vector,
) {
    let reader = unsafe { VectorReader::new(input, 0) };
    let mut writer = unsafe { VectorWriter::new(output) };

    for row in 0..reader.row_count() {
        if unsafe { !reader.is_valid(row) } {
            unsafe { writer.set_null(row) };
            continue;
        }
        let value = unsafe { reader.read_i64(row) };
        unsafe { writer.write_i64(row, transform(value)) };
    }
}
}

Values & Parameter Extraction

DuckDB hands an extension single values — a table function's bind-time parameters, the options of a COPY statement, a folded constant expression — as duckdb_value handles, which are heap-allocated and must be destroyed after use. quack-rs wraps them in Value, which destroys the handle on drop and reads it through typed getters that return Option instead of aborting on SQL NULL. This page covers reading parameters with Value, building values, and nested (LIST, STRUCT, MAP) values.

The problem

Without Value, every parameter extraction requires three raw FFI calls and careful manual cleanup:

#![allow(unused)]
fn main() {
use libduckdb_sys::*;
unsafe fn demo(info: duckdb_bind_info) {
// Before: raw FFI — easy to leak memory, and `duckdb_get_int64` aborts the
// process if the argument is SQL NULL (DuckDB throws a C++ exception).
let mut param = unsafe { duckdb_bind_get_parameter(info, 0) };
let n = unsafe { duckdb_get_int64(param) };
unsafe { duckdb_destroy_value(&mut param) };  // forget this → memory leak
}
}

The solution: Value

Value wraps a duckdb_value handle and calls duckdb_destroy_value on drop:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
use quack_rs::table::BindInfo;

unsafe extern "C" fn my_bind(info: duckdb_bind_info) {
    let bind_info = unsafe { BindInfo::new(info) };

    // Value is RAII — automatically destroyed when dropped.
    // `as_i64` is `None` for SQL NULL; `as_i64_or` supplies a default.
    let n = unsafe { bind_info.get_parameter_value(0) }.as_i64_or(0);

    // Named parameters work the same way
    let path = unsafe { bind_info.get_named_parameter_value("path") }
        .as_str()
        .unwrap_or_default();
}
}

Typed extraction methods

The scalar getters cast the way SQL's TRY_CAST does: a VARCHAR '42' reads as Some(42) through as_i64(), a DOUBLE 1.5 as Some(2) through as_i32(). They return None when:

• the value is SQL NULL (for example my_func(n := NULL)),
• the handle is null (a named parameter the caller did not supply),
• the type is not a scalar (LIST, STRUCT, MAP, BLOB, ENUM, …), or
• the cast fails ('abc', or a number out of range for the target), or
• for the temporal getters, SQL would refuse the conversion: the time of an infinite timestamp (as_time() of 'infinity'::TIMESTAMP), a TIMESTAMP outside TIMESTAMP_NS's 1677–2262 range read with as_timestamp_ns(), or a result outside the target type's range.

No getter calls a duckdb_get_* function in the first three cases — those functions abort the process on a SQL NULL and crash on a null handle — and none modifies the value it reads (DuckDB's getters cast the value in place; quack-rs reads from a copy). The temporal cases are checked before the call too: DuckDB converts those pairs with a cast that throws a C++ exception instead of failing, which aborts the process from Rust.

as_blob() copies the bytes into an owned Vec<u8> without UTF-8 validation. It accepts only a BLOB: DuckDB's conversion of anything else to BLOB can throw. Use as_str() for text.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe fn demo(bind_info: BindInfo) -> Result<(), ExtensionError> {
let bytes = unsafe { bind_info.get_parameter_value(0) }.as_blob()?;
Ok(())
}
}

Defaulting variants

The integer (except as_u128), float, bool and string getters have an _or(default) variant that returns default wherever the plain getter returns None (or Err); as_str_or_default() returns an empty string:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
// Values are DuckDB objects: fill the dispatch table first.
std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
let val = Value::null_value();
let timeout = val.as_i64_or(30);       // 30 if NULL, absent, or not a number
let host = val.as_str_or("localhost");  // "localhost" if NULL or absent
let port = val.as_u16_or(5432);        // 5432 if NULL, absent, or out of range
assert_eq!((timeout, host.as_str(), port), (30, "localhost", 5432));
}

Checking for NULL

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
unsafe fn demo(bind_info: BindInfo) {
let val = unsafe { bind_info.get_named_parameter_value("limit") };
if val.is_null() {
    // the handle is null: the named parameter was not provided
}
if val.is_sql_null() {
    // the parameter was provided as SQL NULL
}
}
}

Escape hatch

If you need the raw handle for an API quack-rs does not wrap, as_raw() borrows it and into_raw() takes ownership:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
use libduckdb_sys::duckdb_value;
unsafe fn demo(bind_info: BindInfo) {
let val = unsafe { bind_info.get_parameter_value(0) };
let raw: duckdb_value = val.into_raw();  // takes ownership, no auto-destroy
// ... use raw handle ...
// caller must call duckdb_destroy_value manually
}
}

Building values

Value::bigint, Value::varchar, Value::date, Value::interval and the other scalar constructors are infallible, with two exceptions that return Result<Value, ExtensionError>:

• The temporal constructors that take a raw 64-bit payload — time, time_tz, time_ns (with duckdb-1-5), timestamp, timestamp_tz, timestamp_s, timestamp_ms and timestamp_ns. DuckDB stores any payload unchecked, and rendering or casting an out-of-range one aborts, crashes or prints garbage, so quack-rs accepts exactly the range DuckDB's SQL produces (TIME 00:00:00–24:00:00, the TIMESTAMP span 290309-12-22 (BC)–294247-01-10 plus ±infinity, and so on) and returns an error otherwise.
• Value::decimal(width, scale, unscaled), which checks that width is 1..=38, scale <= width and unscaled has at most width digits.

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_bind_info, duckdb_connection,
    duckdb_data_chunk, duckdb_function_info, duckdb_init_info, duckdb_vector, idx_t};
use quack_rs::prelude::*;
// Values are DuckDB objects: fill the dispatch table first.
std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
let noon = Value::time(12 * 3_600 * 1_000_000)?;
assert!(Value::time(-1).is_err());
assert_eq!(noon.as_time(), Some(12 * 3_600 * 1_000_000));
Ok::<(), ExtensionError>(())
}

To build a nested value, Value::list_value and Value::array_value take the element type and the items, Value::struct_value the STRUCT type and one value per field, and Value::enum_value the ENUM type and an index; Value::map and Value::union_value need duckdb-1-5. All return Result<Value, ExtensionError>.

Reading nested values

A parameter of type LIST, STRUCT or MAP is read element by element; each accessor that returns a Value returns an owned one.

#![allow(unused)]
fn main() {
use quack_rs::value::Value;
fn demo(options: &Value) -> Option<String> {
let names = options.struct_field_names();
let idx = names.iter().position(|n| n == "compression")?;
options.struct_child(idx)?.as_str().ok()
}
}

DataChunk, which wraps the chunk a table function's scan callback writes its output to, is described in Reading & Writing Vectors.

Complex Types: STRUCT, LIST, MAP, ARRAY

DuckDB stores its nested types — STRUCT, LIST, MAP and ARRAY — as a parent vector with one or more child vectors. This page shows how a quack-rs extension reads and writes them: the four helper types in vector::complex reach the child vectors, and ListBuilder writes LIST and MAP output without manual offset arithmetic.

Overview

Reading complex types (input vectors)

STRUCT

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_vector;
fn demo(parent_vec: duckdb_vector, row_count: usize) {
use quack_rs::vector::{VectorReader, complex::StructVector};

// Inside a scalar function or aggregate update callback:
// parent_vec comes from duckdb_data_chunk_get_vector(chunk, col_idx)
let x_reader = unsafe { StructVector::field_reader(parent_vec, 0, row_count) };
let y_reader = unsafe { StructVector::field_reader(parent_vec, 1, row_count) };

for row in 0..row_count {
    // Each field has its own validity bitmap.
    if unsafe { x_reader.is_valid(row) && y_reader.is_valid(row) } {
        let x: f64 = unsafe { x_reader.read_f64(row) };
        let y: f64 = unsafe { y_reader.read_f64(row) };
        // process (x, y) …
    }
}
}
}

LIST

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_vector;
fn demo(list_vec: duckdb_vector, row_count: usize) {
use quack_rs::vector::{VectorReader, complex::ListVector};

let total_elements = unsafe { ListVector::get_size(list_vec) };
let elem_reader = unsafe { ListVector::child_reader(list_vec, total_elements) };

for row in 0..row_count {
    let entry = unsafe { ListVector::get_entry(list_vec, row) };
    for i in 0..entry.length as usize {
        let elem_idx = entry.offset as usize + i;
        if unsafe { elem_reader.is_valid(elem_idx) } {
            let val: i64 = unsafe { elem_reader.read_i64(elem_idx) };
            // process val …
        }
    }
}
}
}

MAP

MAP is LIST<STRUCT{key, value}>. MapVector::key_reader and value_reader read the two fields of the inner struct:

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_vector;
fn demo(map_vec: duckdb_vector, row_count: usize) {
use quack_rs::vector::complex::MapVector;

let total = unsafe { MapVector::total_entry_count(map_vec) };
let key_reader   = unsafe { MapVector::key_reader(map_vec, total) };
let value_reader = unsafe { MapVector::value_reader(map_vec, total) };

for row in 0..row_count {
    let entry = unsafe { MapVector::get_entry(map_vec, row) };
    for i in 0..entry.length as usize {
        let idx = entry.offset as usize + i;
        let k = unsafe { key_reader.read_str(idx) };   // MAP keys are never NULL
        if unsafe { value_reader.is_valid(idx) } {
            let v: i64 = unsafe { value_reader.read_i64(idx) };
            // process (k, v) …
        }
    }
}
}
}

Writing complex types (output vectors)

STRUCT

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_vector;
fn demo(out_vec: duckdb_vector, batch_size: usize, x_values: &[f64], y_values: &[f64]) {
use quack_rs::vector::{VectorWriter, complex::StructVector};

let mut x_writer = unsafe { StructVector::field_writer(out_vec, 0) };
let mut y_writer = unsafe { StructVector::field_writer(out_vec, 1) };

for row in 0..batch_size {
    unsafe { x_writer.write_f64(row, x_values[row]) };
    unsafe { y_writer.write_f64(row, y_values[row]) };
}
}
}

Nested complex types inside STRUCT (v0.11.0+)

When a STRUCT field is itself a LIST, MAP or ARRAY, child_vector(field_idx) on StructWriter or StructReader returns the field's raw vector handle, which the ListVector, MapVector and ArrayVector helpers and ListBuilder accept:

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_vector;
fn demo(struct_vec: duckdb_vector, row: usize) {
use quack_rs::vector::{ListBuilder, StructWriter};

// STRUCT(name VARCHAR, services VARCHAR[], message VARCHAR)
let mut sw = unsafe { StructWriter::new(struct_vec, 3) };

// Write scalar fields normally
unsafe { sw.write_varchar(row, 0, "hello") };
unsafe { sw.write_varchar(row, 2, "ok") };

// The LIST field at index 1: ListBuilder appends after any elements
// earlier rows already wrote to the child vector.
let services = ["a", "b", "c"];
let mut builder = unsafe { ListBuilder::new(sw.child_vector(1)) };
unsafe {
    builder.push_row(row, services.len(), |writer, base| {
        for (i, s) in services.iter().enumerate() {
            writer.write_varchar(base + i, s);
        }
    });
    builder.finish();
}
}
}

LIST — recommended: ListBuilder

ListBuilder tracks the running offset, writes each parent row's {offset, length} entry, and — importantly — re-fetches the child writer after every reserve:

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_vector;
fn demo(list_vec: duckdb_vector, rows: &[Vec<i64>]) {
use quack_rs::vector::ListBuilder;

let mut builder = unsafe { ListBuilder::new(list_vec) };
for (row, elements) in rows.iter().enumerate() {
    unsafe {
        builder.push_row(row, elements.len(), |writer, base| {
            for (i, &val) in elements.iter().enumerate() {
                writer.write_i64(base + i, val);
            }
        });
    }
}
unsafe { builder.finish() };
}
}

Why the re-fetch matters. duckdb_list_vector_reserve takes a total capacity, and when it grows it reallocates the child vector's data buffer. A VectorWriter obtained before that call is left holding a dangling pointer. The manual pattern below is safe only because it reserves exactly once, before any writer exists — which requires knowing the total element count up front. ListBuilder has no such requirement. The same applies to writers on anything below the child, such as the fields of a LIST of STRUCTs: fetch them again after every reserve that grows the list (see Pitfall L18).

push_map_row does the same for MAP, handing the closure a writer for the key child and one for the value child.

DuckDB limits a child vector to 2^37 bytes per buffer (MAX_LIST_CHILD_CAPACITY), and a reservation above that — or one the allocator cannot satisfy — throws a C++ exception through the C API, which aborts the process. vector::max_child_capacity(vec) turns the byte limit into an element count for the child's type: 2^34 BIGINTs, 2^33 VARCHARs. ListBuilder applies it by itself. When row lengths come from untrusted input, also set a limit that fits in memory with with_element_limit(n): a row that would exceed the limit is written as NULL instead, and overflowed() reports that it happened.

LIST — manual

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_vector;
fn demo(list_vec: duckdb_vector, rows: &[Vec<i64>]) {
use quack_rs::vector::{VectorWriter, complex::ListVector};

let total_elements: usize = rows.iter().map(|r| r.len()).sum();
// Must not exceed quack_rs::vector::max_child_capacity(list_vec); see above.
unsafe { ListVector::reserve(list_vec, total_elements) };

let mut child_writer = unsafe { ListVector::child_writer(list_vec) };
let mut offset = 0usize;
for (row, elements) in rows.iter().enumerate() {
    for (i, &val) in elements.iter().enumerate() {
        unsafe { child_writer.write_i64(offset + i, val) };
    }
    unsafe { ListVector::set_entry(list_vec, row, offset as u64, elements.len() as u64) };
    offset += elements.len();
}
unsafe { ListVector::set_size(list_vec, total_elements) };
}
}

MAP — manual

Writing a MAP follows the LIST pattern, but keys and values go into the two fields of the inner STRUCT vector. Prefer ListBuilder::push_map_row unless you know the total pair count before writing:

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_vector;
fn demo(map_vec: duckdb_vector, total_pairs: usize, all_pairs: &[Vec<(String, i64)>]) {
use quack_rs::vector::complex::MapVector;

unsafe { MapVector::reserve(map_vec, total_pairs) };

let mut key_writer = unsafe { MapVector::key_writer(map_vec) };
let mut val_writer = unsafe { MapVector::value_writer(map_vec) };
let mut offset = 0usize;
for (row, pairs) in all_pairs.iter().enumerate() {
    for (i, (k, v)) in pairs.iter().enumerate() {
        unsafe { key_writer.write_varchar(offset + i, k) };
        unsafe { val_writer.write_i64(offset + i, *v) };
    }
    unsafe { MapVector::set_entry(map_vec, row, offset as u64, pairs.len() as u64) };
    offset += pairs.len();
}
unsafe { MapVector::set_size(map_vec, total_pairs) };
}
}

Constructing complex logical types

Use LogicalType constructors to define complex column types. Each constructor has a variant that accepts TypeId values (for simple element types) and a _from_logical variant (for nested complex types):

Each constructor also has a try_ form (try_list, try_struct_type_from_logical, …) that returns Result<LogicalType, LogicalTypeError>; the plain forms panic where the try_ form returns an error. Errors include a composite TypeId passed where a _from_logical variant is needed, STRUCT field or UNION member names that are equal ignoring ASCII case, and a UNION with more than MAX_UNION_MEMBERS (255) members.

API reference

All helpers are in quack_rs::vector::complex (re-exported from quack_rs::prelude).

StructVector

StructWriter / StructReader complex field access (v0.11.0+)

ListVector

MapVector

ArrayVector

NULL Handling & Strings

This page covers checking for NULL before reading a DuckDB vector, writing NULL output, and reading and writing VARCHAR and BLOB values. The two topics belong together: reading a string from a NULL row is undefined behaviour, not just a wrong value.

NULL checks

Every row in a DuckDB vector may be NULL. Always check validity before reading:

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(reader: &VectorReader, writer: &mut VectorWriter) {
for row in 0..reader.row_count() {
    if unsafe { !reader.is_valid(row) } {
        // Propagate NULL to output
        unsafe { writer.set_null(row) };
        continue;
    }
    // Safe to read
    let value = unsafe { reader.read_str(row) };
}
}
}

Reading a fixed-width value from a NULL row returns garbage. The vector's data buffer is not zeroed at NULL positions, and no error is raised: you get whatever bytes the buffer holds at that position.

For VARCHAR and BLOB it is worse than garbage. A NULL row's 16-byte entry is left as it was, and DuckDB reuses vector buffers between chunks, so the entry can still be the pointer-format record of a string from an earlier chunk whose memory may since have been freed or reused. read_str / read_blob on such a row follow that pointer: undefined behaviour, not merely a wrong answer. Their # Safety sections require the row to be valid.

Writing NULL

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(writer: &mut VectorWriter, row: usize) {
unsafe { writer.set_null(row) };
}
}

Pitfall L4: VectorWriter::set_null calls duckdb_vector_ensure_validity_writable before accessing the validity bitmap. Without it, a vector that has no mask yet makes duckdb_vector_get_validity return NULL, and the NULL you write is silently dropped. Never write NULL manually; always use set_null — which, for a STRUCT or ARRAY output, also nulls the fields / elements of that row the way DuckDB expects. See Pitfall L4.

Clearing NULL (v0.11.0+)

To mark a row as valid after a previous set_null:

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(writer: &mut VectorWriter, row: usize) {
unsafe { writer.set_valid(row) };
}
}

VARCHAR reading

Read VARCHAR columns with VectorReader::read_str:

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(reader: &VectorReader, row: usize) {
let s: &str = unsafe { reader.read_str(row) };
}
}

The returned &str borrows from the DuckDB vector — it must not outlive the callback. Do not store it in a struct; clone it to a String if you need to keep it.

The duckdb_string_t format

Pitfall P7: the Rust bindings do not document the layout of duckdb_string_t. quack-rs decodes it for you; the details below are for reference. See Pitfall P7.

DuckDB stores VARCHAR values in a 16-byte duckdb_string_t struct with two representations, selected at runtime based on string length:

On a 32-bit target (DuckDB-WASM) the pointer is 4 bytes and the last 4 bytes are unused. The length and the pointer are in the target's byte order.

VectorReader::read_str and the underlying read_duck_string function handle both formats, so you do not need to inspect the raw struct. A value that is not valid UTF-8 is returned as ""; use read_blob to get its bytes.

Empty strings vs NULL

An empty string ("") and NULL are distinct values:

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(reader: &VectorReader, row: usize) {
// NULL: is_valid returns false
// Empty string: is_valid returns true, read_str returns ""
if unsafe { !reader.is_valid(row) } {
    // This is NULL
} else {
    let s = unsafe { reader.read_str(row) };
    if s.is_empty() {
        // This is an empty string, not NULL
    }
}
}
}

Writing VARCHAR

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(writer: &mut VectorWriter, row: usize, my_str: &str) {
unsafe { writer.write_varchar(row, my_str) };  // &str
}
}

write_varchar copies the string bytes into DuckDB's managed storage, so the &str need not outlive the call. write_blob does the same for &[u8].

Both panic for a value longer than MAX_STRING_LEN (u32::MAX bytes, the most a duckdb_string_t length field can hold) instead of storing a truncated value; inside scalar_callback! and the typed scalar constructors the panic becomes a SQL error. try_write_varchar and try_write_blob return Result<(), ExtensionError> instead and write nothing on error:

#![allow(unused)]
fn main() {
use quack_rs::vector::VectorWriter;
use quack_rs::error::ExtensionError;
fn demo(writer: &mut VectorWriter, row: usize, my_str: &str) -> Result<(), ExtensionError> {
unsafe { writer.try_write_varchar(row, my_str)? };
Ok(())
}
}

Reading BLOB values

BLOB uses the same inline/pointer layout as VARCHAR, but may contain any bytes. Use read_blob so the data is not interpreted as UTF-8:

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(reader: &VectorReader, row: usize) {
let bytes: &[u8] = unsafe { reader.read_blob(row) };
}
}

Like read_str, the returned slice borrows from the DuckDB vector and must not outlive the callback.

Complete NULL-safe VARCHAR pattern

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_data_chunk, duckdb_function_info, duckdb_vector};
use quack_rs::vector::{VectorReader, VectorWriter};
unsafe extern "C" fn my_scalar(
    _info: duckdb_function_info,
    input: duckdb_data_chunk,
    output: duckdb_vector,
) {
    let reader = unsafe { VectorReader::new(input, 0) };
    let mut writer = unsafe { VectorWriter::new(output) };

    for row in 0..reader.row_count() {
        if unsafe { !reader.is_valid(row) } {
            unsafe { writer.set_null(row) };
            continue;
        }
        let s = unsafe { reader.read_str(row) };
        let upper = s.to_uppercase();
        unsafe { writer.write_varchar(row, &upper) };
    }
}
}

DuckStringView

For advanced use cases where you need access to the raw string bytes or the inline/pointer distinction, quack_rs::vector::string::DuckStringView is available:

#![allow(unused)]
fn main() {
fn demo(data: *const u8, idx: usize) {
use quack_rs::vector::string::{DuckStringView, DUCK_STRING_SIZE};

// From raw 16-byte data (inside a vector callback). `from_raw` is unsafe because it
// follows the pointer of a string longer than 12 bytes; untrusted bytes go through
// `DuckStringView::inline_from_bytes`, which refuses that format instead.
let raw: &[u8; 16] = unsafe { &*data.add(idx * DUCK_STRING_SIZE).cast() };
let view = unsafe { DuckStringView::from_raw(raw) };

println!("length: {}", view.len());
println!("is_empty: {}", view.is_empty());
if let Some(s) = view.as_str() {
    println!("content: {s}");
}
}
}

In practice, prefer reader.read_str(row). DuckStringView is needed only when you have a raw data pointer rather than a VectorReader. Unlike read_str, its as_str returns None, not "", for a value that is not valid UTF-8.

Constants

All three are in quack_rs::vector::string.

INTERVAL Type

DuckDB's INTERVAL type represents a duration with three independent components: months, days and microseconds. The quack_rs::interval module provides the DuckInterval struct, which matches DuckDB's in-memory layout, and overflow-safe conversions to microseconds.

Why a custom struct?

Pitfall P8: the Rust bindings do not document the INTERVAL layout or how DuckDB converts intervals. DuckInterval and the functions below encode both. See Pitfall P8.

DuckDB's C duckdb_interval struct is 16 bytes with this exact layout:

offset 0:  months (i32)  — calendar months
offset 4:  days   (i32)  — calendar days
offset 8:  micros (i64)  — microseconds (not limited to one day)
total:     16 bytes

DuckInterval is #[repr(C)] with the same field order, and a compile-time assertion checks that it is exactly 16 bytes.

Reading INTERVAL values

#![allow(unused)]
fn main() {
use quack_rs::interval::DuckInterval;
use quack_rs::vector::VectorReader;
fn demo(reader: &VectorReader, row: usize) {
let iv: DuckInterval = unsafe { reader.read_interval(row) };
println!("{} months, {} days, {} µs", iv.months, iv.days, iv.micros);
}
}

VectorReader::read_interval handles the raw pointer arithmetic and alignment using read_interval_at internally.

DuckInterval fields

#![allow(unused)]
fn main() {
use quack_rs::interval::DuckInterval;

let iv = DuckInterval {
    months: 1,    // 1 calendar month
    days: 15,     // 15 calendar days
    micros: 3_600_000_000, // 1 hour in microseconds
};
}

The fields are public, so a DuckInterval can be built directly.

The derived PartialEq, Eq and Hash compare the three fields, so { months: 1, .. } and { days: 30, .. } are different values here, while in SQL INTERVAL '1 month' = INTERVAL '30 days' is true.

Zero interval

#![allow(unused)]
fn main() {
use quack_rs::interval::DuckInterval;
let zero = DuckInterval::zero();    // { months: 0, days: 0, micros: 0 }
let zero = DuckInterval::default(); // same
assert_eq!(zero, DuckInterval::zero());
}

Converting to microseconds

Months and days have no fixed length in wall-clock time, so an interval has no single exact length. When you need one number, for ordering or bucketing, convert to microseconds with the approximation DuckDB uses when it compares intervals and in epoch_us(interval): 1 month = 30 days.

This is not date arithmetic: DuckDB adds an interval to a date by calendar months (DATE '2024-01-31' + INTERVAL 1 MONTH is 2024-02-29). It also matches SQL comparison only when the three fields share a sign: INTERVAL '1 month' - INTERVAL '1 day' converts to the same total as INTERVAL '29 days' but compares greater in SQL.

Checked conversion (returns Option)

#![allow(unused)]
fn main() {
use quack_rs::interval::DuckInterval;
use quack_rs::interval::interval_to_micros;

let iv = DuckInterval { months: 0, days: 1, micros: 500_000 };
match interval_to_micros(iv) {
    Some(us) => println!("{us} microseconds"),
    None => println!("overflow"),
}

// Method form:
let us: Option<i64> = iv.to_micros();
assert_eq!(us, Some(86_400_000_000 + 500_000));
}

Returns None if the total does not fit in an i64, which takes extreme values such as months: i32::MAX, days: i32::MAX, micros: i64::MAX. The sum is computed exactly, so large fields of opposite signs that cancel out still convert.

Saturating conversion (returns i64)

#![allow(unused)]
fn main() {
use quack_rs::interval::DuckInterval;
use quack_rs::interval::interval_to_micros_saturating;

let iv = DuckInterval { months: i32::MAX, days: i32::MAX, micros: i64::MAX };
let us: i64 = interval_to_micros_saturating(iv); // i64::MAX

// Method form:
let us: i64 = iv.to_micros_saturating();
assert_eq!(us, i64::MAX);
assert_eq!(interval_to_micros_saturating(iv), i64::MAX);
}

The saturating form clamps an out-of-range total to i64::MAX or i64::MIN. Neither form panics; use the checked form when an overflow must be reported rather than clamped.

Conversion constants

#![allow(unused)]
fn main() {
use quack_rs::interval::{MICROS_PER_DAY, MICROS_PER_MONTH};

assert_eq!(MICROS_PER_DAY, 86_400 * 1_000_000);
assert_eq!(MICROS_PER_MONTH, 30 * MICROS_PER_DAY);
}

Low-level: read_interval_at

If you have a raw data pointer (e.g., from duckdb_vector_get_data), you can read an interval directly:

#![allow(unused)]
fn main() {
fn demo(data_ptr: *const u8, row_idx: usize) {
use quack_rs::interval::read_interval_at;

// SAFETY: data is a valid DuckDB INTERVAL vector data pointer, idx is in bounds.
let iv = unsafe { read_interval_at(data_ptr, row_idx) };
}
}

In practice, use VectorReader::read_interval(row), which computes the data pointer for you; its remaining unsafe contract is the row index and the column type.

Complete example: aggregate over INTERVAL

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_aggregate_state, duckdb_data_chunk, duckdb_function_info};
use quack_rs::aggregate::{AggregateState, FfiState};
use quack_rs::vector::VectorReader;
#[derive(Default)]
struct TotalDurationState {
    total_micros: i64,
}
impl AggregateState for TotalDurationState {}

unsafe extern "C" fn update(
    _info: duckdb_function_info,
    input: duckdb_data_chunk,
    states: *mut duckdb_aggregate_state,
) {
    let reader = unsafe { VectorReader::new(input, 0) };
    for row in 0..reader.row_count() {
        if unsafe { !reader.is_valid(row) } { continue; }
        let iv = unsafe { reader.read_interval(row) };
        let us = iv.to_micros_saturating();
        let state_ptr = unsafe { *states.add(row) };
        if let Some(st) = unsafe { FfiState::<TotalDurationState>::with_state_mut(state_ptr) } {
            st.total_micros = st.total_micros.saturating_add(us);
        }
    }
}
}

Memory layout verification

A compile-time assertion checks that DuckInterval is 16 bytes with at least 4-byte alignment, the layout of DuckDB's duckdb_interval. If it fails, the crate does not compile, so a layout change is caught at build time rather than at run time.

Dates, Times and Timestamps

VectorReader and VectorWriter read and write DuckDB's DATE, TIME, TIMETZ, TIMESTAMP and INTERVAL values as the raw integers DuckDB stores; quack_rs::datetime converts them to and from calendar fields. This page also covers DECIMAL and HUGEINT, whose conversions live in the same module.

Turning those integers into year/month/day means implementing the proleptic Gregorian calendar, and getting it to agree with DuckDB's SQL semantics exactly rather than approximately. DuckDB already exposes the conversions, and they are in the stable prefix of the C API, so quack_rs::datetime wraps them instead of reimplementing them. They need no feature flag.

Decomposing and composing

#![allow(unused)]
fn main() {
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(reader: &VectorReader, writer: &mut VectorWriter, row: usize) {
use quack_rs::datetime;

// DATE -> calendar date
let days = unsafe { reader.read_date(row) };
let date = unsafe { datetime::date_from_days(days) };
println!("{:04}-{:02}-{:02}", date.year, date.month, date.day);

// …and back. `None` means DuckDB cannot represent the date.
match unsafe { datetime::date_to_days(date) } {
    Some(days) => unsafe { writer.write_date(row, days) },
    None => unsafe { writer.set_null(row) },
}
}
}

Time, TimeTz and Timestamp work the same way:

#![allow(unused)]
fn main() {
use quack_rs::datetime;
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(reader: &VectorReader, writer: &mut VectorWriter, rows: usize) {
for row in 0..rows {
let Some(ts) = (unsafe { datetime::timestamp_from_micros(reader.read_timestamp(row)) }) else {
    // ±infinity (or the first ~4 hours of the i64 range): no calendar form.
    unsafe { writer.set_null(row) };
    continue;
};
assert!((0..1_000_000).contains(&ts.time.micros));   // ts.date and ts.time are plain structs

let micros = unsafe { datetime::timestamp_to_micros(ts) };   // Option<i64>
}
}
}

Invalid input is None, not an abort

Several of DuckDB's conversions throw a C++ exception on bad input, and the C API does not catch it — so calling them directly with, say, month 13 aborts the whole process ("Rust cannot catch foreign exceptions"). The wrappers apply DuckDB's own conditions first and return None instead:

time_from_micros and time_tz_from_bits guard an assertion rather than an exception: a release build of DuckDB decomposes an out-of-range time into out-of-range fields, and a build with assertions enabled aborts.

time_to_micros does no range check, exactly like DuckDB: an hour of 25 simply gives a TIME past midnight.

TIMETZ is a packed 64-bit value, not a plain integer — build and read it through the helpers rather than by hand:

#![allow(unused)]
fn main() {
use quack_rs::datetime;
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(reader: &VectorReader, writer: &mut VectorWriter, row: usize) {
let bits = unsafe { datetime::time_tz_bits(12 * 3_600 * 1_000_000, -5 * 3_600) }
    .expect("noon, UTC-5, is in range");
unsafe { writer.write_time_tz(row, bits) };

let decoded = unsafe { datetime::time_tz_from_bits(reader.read_time_tz(row)) }
    .expect("DuckDB wrote a valid TIMETZ");
assert_eq!(decoded.offset_seconds, -5 * 3_600);
}
}

Infinity

DuckDB reserves two values of DATE and of TIMESTAMP for infinity and -infinity. Decomposing one into a calendar date is meaningless, so check first:

#![allow(unused)]
fn main() {
use quack_rs::datetime;
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(reader: &VectorReader, writer: &mut VectorWriter, row: usize) {
let days = unsafe { reader.read_date(row) };
if unsafe { datetime::is_finite_date(days) } {
    let date = unsafe { datetime::date_from_days(days) };
    // …
}
}
}

Note the exact values, which are easy to get wrong:

Negative infinity is -i32::MAX, not i32::MIN. i32::MIN is an ordinary (if absurd) finite date, and treating it as infinity would silently drop real rows.

DECIMAL

DECIMAL is stored in the narrowest integer that fits its declared width, so the width has to travel with the value:

read_decimal / write_decimal take the width and pick the right one. Get it from the column's LogicalType:

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_vector;
use quack_rs::vector::{VectorReader, VectorWriter};
fn demo(vec: duckdb_vector, reader: &VectorReader, writer: &mut VectorWriter, row: usize) {
let logical = unsafe { quack_rs::vector::vector_get_column_type(vec) };
let width = unsafe { logical.decimal_width() };
let scale = unsafe { logical.decimal_scale() };

let unscaled = unsafe { reader.read_decimal(row, width) };
// The represented number is unscaled / 10^scale. The doubled value must
// still fit in `width` digits; write_decimal does not check.
unsafe { writer.write_decimal(row, width, unscaled * 2) };
}
}

datetime::f64_to_decimal and datetime::decimal_to_f64 convert through DuckDB's own routines when a floating-point view is what you want. decimal_to_f64 returns None for a width above 38 or a scale above the width: DuckDB would index its powers-of-ten table out of bounds.

Wide integers

HUGEINT is { lower: u64, upper: i64 } and UHUGEINT is two u64s. read_i128 / write_i128 and read_u128 / write_u128 handle the halves; datetime::hugeint_to_f64, f64_to_hugeint, uhugeint_to_f64 and f64_to_uhugeint convert through DuckDB's own routines, so they round as DuckDB does.

Running SQL from an Extension

Extensions often need to run SQL against the database that is loading them: checking whether a table exists before registering a replacement scan, creating a helper view, reading a setting, or looking up a credential through duckdb_secrets(). This page covers queries, prepared statements with bound parameters, keeping a connection for use after loading, and cancelling a running query.

The C API has everything for that — duckdb_query, duckdb_prepare, duckdb_bind_*, duckdb_fetch_chunk — and all of it is in the stable prefix, so it needs no feature flag. What it does not have is any help releasing the handles: every one of them has a matching destroy that must run exactly once, including on the error paths, which is where hand-written FFI usually leaks.

quack_rs::query wraps them:

During registration

Connection (from entry_point_v2!) can run SQL directly:

#![allow(unused)]
fn main() {
use quack_rs::connection::Connection;
use quack_rs::error::ExtensionError;

fn register(con: &Connection) -> Result<(), ExtensionError> {
    // Create a helper view the extension's functions rely on.
    unsafe { con.execute("CREATE OR REPLACE VIEW my_ext_config AS SELECT 1 AS version") }?;

    // Read something back. The cast makes the column VARCHAR, which read_str requires.
    let mut result = unsafe { con.query("SELECT current_setting('threads')::VARCHAR") }?;
    if let Some(chunk) = result.next_chunk()? {
        // The reader must outlive the `&str` it hands out, so bind it first.
        let reader = unsafe { chunk.reader(0) };
        let threads = unsafe { reader.read_str(0) };
        eprintln!("DuckDB is using {threads} threads");
    }
    Ok(())
}
}

Results arrive a chunk at a time — at most duckdb_vector_size() rows each — so call next_chunk until it returns Ok(None):

#![allow(unused)]
fn main() {
use quack_rs::error::ExtensionError;
use quack_rs::query::OwnedConnection;
// `Connection` (from entry_point_v2!) only exists during an extension load. An
// `OwnedConnection` has the same query / execute / prepare methods.
std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
let mut db = std::ptr::null_mut();
unsafe { assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), libduckdb_sys::DuckDBSuccess); }
let con = unsafe { OwnedConnection::open(db) }.unwrap();
let run = || -> Result<(), ExtensionError> {
let mut result = unsafe { con.query("SELECT i FROM range(10000) t(i)") }?;
let mut total: i64 = 0;
while let Some(chunk) = result.next_chunk()? {
    let reader = unsafe { chunk.reader(0) };
    for row in 0..chunk.size() {
        total += unsafe { reader.read_i64(row) };
    }
}
assert_eq!(total, 49_995_000);
Ok(()) };
run().unwrap();
}

next_chunk returns Result<Option<OwnedDataChunk>, ExtensionError> because a result can stop early. A streaming result (PreparedStatement::execute_streaming, with the duckdb-1-5 feature) produces rows as it runs, so a runtime error part-way through, an interrupt, or another statement run on the same connection (which invalidates the stream) surfaces at next_chunk. The C API reports that the same way as the end of the rows (a null chunk); quack-rs reads the error DuckDB recorded and returns it, so a partial result cannot pass for a complete one. The ? above is what keeps it from being silently truncated. After Ok(None) or an error, later calls return the same thing.

Inspecting a result

Several statements in one string

query and execute accept several ;-separated statements, and DuckDB runs every one, in order. The result you get back is the first statement that produces rows — or, when none does, the last statement's; the results of later row-producing statements are discarded. So "SELECT 1; INSERT …" runs the INSERT but execute reports 0 rows changed. The first failing statement fails the call, after the ones before it have run (and, outside an explicit transaction, committed). An empty string, or just ;, succeeds with an empty result. prepare takes exactly one statement.

Bind values, do not interpolate them

Anything that did not come from your own source text — a table name from a function argument, a path from a config option — goes through a parameter. Parameters are 1-indexed, matching the C API.

#![allow(unused)]
fn main() {
use quack_rs::error::ExtensionError;
use quack_rs::query::OwnedConnection;
// `Connection` (from entry_point_v2!) only exists during an extension load. An
// `OwnedConnection` has the same query / execute / prepare methods.
std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
let mut db = std::ptr::null_mut();
unsafe { assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), libduckdb_sys::DuckDBSuccess); }
let con = unsafe { OwnedConnection::open(db) }.unwrap();
con.execute("CREATE TABLE audit (name VARCHAR, n BIGINT)").unwrap();
let user_supplied_name = "O'Brien'); DROP TABLE audit; --";
let run = || -> Result<(), ExtensionError> {
let stmt = unsafe { con.prepare("INSERT INTO audit VALUES (?, ?)") }?;
stmt.bind_str(1, user_supplied_name)?;   // safe even if it contains quotes
stmt.bind_i64(2, 42)?;
stmt.execute()?;
let mut r = con.query("SELECT count(*) FROM audit WHERE name LIKE 'O''Brien%'")?;
assert_eq!(unsafe { r.next_chunk()?.unwrap().reader(0).read_i64(0) }, 1);
Ok(()) };
run().unwrap();
}

bind_str passes the length explicitly, so embedded NUL bytes are preserved and no CString conversion can fail.

There is a typed bind for every integer width (bind_i8 … bind_u128), bind_f32 / bind_f64, bind_bool, bind_blob, bind_null, bind_decimal, bind_date, bind_time, bind_timestamp, bind_timestamp_tz and bind_interval. bind_value takes any Value, which covers the composite types. Like the Value constructors, bind_decimal validates width, scale and digit count, and bind_time and the timestamp binds refuse a payload outside the range DuckDB's SQL produces; the C API's duckdb_bind_* functions check nothing.

Named parameters resolve by name:

#![allow(unused)]
fn main() {
use quack_rs::error::ExtensionError;
use quack_rs::query::OwnedConnection;
// `Connection` (from entry_point_v2!) only exists during an extension load. An
// `OwnedConnection` has the same query / execute / prepare methods.
std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
let mut db = std::ptr::null_mut();
unsafe { assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), libduckdb_sys::DuckDBSuccess); }
let con = unsafe { OwnedConnection::open(db) }.unwrap();
con.execute("CREATE TABLE t AS SELECT range AS id FROM range(10)").unwrap();
let id = 7;
let run = || -> Result<(), ExtensionError> {
let stmt = unsafe { con.prepare("SELECT * FROM t WHERE id = $needle") }?;
let index = stmt.parameter_index("needle").expect("named parameter");
stmt.bind_i64(index, id)?;
let mut r = stmt.execute()?;
assert_eq!(unsafe { r.next_chunk()?.unwrap().reader(0).read_i64(0) }, 7);
Ok(()) };
run().unwrap();
}

Reuse a statement by clearing its bindings between executions:

#![allow(unused)]
fn main() {
use quack_rs::error::ExtensionError;
use quack_rs::query::OwnedConnection;
// `Connection` (from entry_point_v2!) only exists during an extension load. An
// `OwnedConnection` has the same query / execute / prepare methods.
std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
let mut db = std::ptr::null_mut();
unsafe { assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), libduckdb_sys::DuckDBSuccess); }
let con = unsafe { OwnedConnection::open(db) }.unwrap();
let run = || -> Result<(), ExtensionError> {
let stmt = con.prepare("SELECT ?::BIGINT * 2")?;
let ids = [1_i64, 2, 3];
for id in ids {
    stmt.clear_bindings()?;
    stmt.bind_i64(1, id)?;
    let mut result = stmt.execute()?;
    // …
}
Ok(()) };
run().unwrap();
}

After registration

The connection DuckDB passes to your entry point is borrowed — the entry point disconnects it when your closure returns. Inside a scalar, table or aggregate callback you have no connection at all: the C API gives you a duckdb_client_context, and there is no duckdb_client_context_get_connection.

If a callback or a background thread needs to run SQL, open your own connection during registration and keep it. A duckdb_connection holds its own reference to the database instance, so it stays valid after loading finishes:

#![allow(unused)]
fn main() {
use quack_rs::connection::Connection;
use quack_rs::error::ExtensionError;
use quack_rs::query::OwnedConnection;
use std::sync::{Mutex, OnceLock};

// `OwnedConnection` is `Send` but not `Sync` (see below), so a `static` must
// hold it behind a `Mutex`.
static CONN: OnceLock<Mutex<OwnedConnection>> = OnceLock::new();

fn register(con: &Connection) -> Result<(), ExtensionError> {
    let owned = unsafe { con.open_connection() }?;
    let _ = CONN.set(Mutex::new(owned));
    Ok(())
}
}

OwnedConnection is Send but deliberately not Sync: DuckDB permits moving a connection between threads, not using one concurrently. Open one connection per thread, or guard it with a mutex.

Cancelling a query and reading its progress

OwnedConnection::interrupt_handle returns an InterruptHandle, which is Send + Sync and borrows the connection, so it cannot outlive it. Another thread can call its cancel() to stop the running query, which then fails with an interrupt error at DuckDB's next check, or its progress() to read a QueryProgress (percentage, rows_processed, total_rows_to_process). percentage is -1.0 when DuckDB cannot report progress, for example when the progress bar is disabled (SET enable_progress_bar = true). OwnedConnection::interrupt and progress do the same on the calling thread.

#![allow(unused)]
fn main() {
use quack_rs::error::ExtensionError;
use quack_rs::query::{OwnedConnection, QueryResult};
use std::sync::mpsc::{channel, RecvTimeoutError};
use std::time::Duration;

fn query_with_timeout(con: &OwnedConnection, sql: &str) -> Result<QueryResult, ExtensionError> {
    let watchdog = con.interrupt_handle();
    let (done, finished) = channel::<()>();
    std::thread::scope(|scope| {
        scope.spawn(move || {
            // Cancel the query if it has not finished within 30 seconds.
            if let Err(RecvTimeoutError::Timeout) = finished.recv_timeout(Duration::from_secs(30)) {
                watchdog.cancel();
            }
        });
        let result = con.query(sql);
        drop(done); // wakes the watchdog
        result
    })
}
}

Errors

Failures carry DuckDB's own message:

#![allow(unused)]
fn main() {
use quack_rs::error::ExtensionError;
use quack_rs::query::OwnedConnection;
// `Connection` (from entry_point_v2!) only exists during an extension load. An
// `OwnedConnection` has the same query / execute / prepare methods.
std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
let mut db = std::ptr::null_mut();
unsafe { assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), libduckdb_sys::DuckDBSuccess); }
let con = unsafe { OwnedConnection::open(db) }.unwrap();
let err = unsafe { con.query("SELECT * FROM no_such_table") }.unwrap_err();
assert!(err.as_str().contains("no_such_table"));
assert_eq!(con.execute("SELECT 1").unwrap(), 0);
}

The connection stays usable afterwards.

Bulk Appender

Appender is an RAII wrapper around DuckDB's appender, the fastest way for an extension to bulk-insert rows into an existing table: rows are buffered and written in batches instead of going through one INSERT statement each. This page covers appending row by row and chunk by chunk, error handling, and what happens when a row fails half-way.

No feature flag required. DuckDB has kept duckdb_appender_* in the frozen stable prefix of the extension API (slots 281–291 and 330–356) since v1.2.0, so using the appender does not push your extension onto the version-pinned unstable ABI. See ABI Compatibility for why that distinction matters. Three methods are the exception and need duckdb-1-5: error_data, clear, and append_default_to_chunk.

Row at a time

Call one append_* per column, then finish the row with end_row. row calls end_row for you when its closure succeeds, so a forgotten end_row cannot leave the table silently short:

#![allow(unused)]
fn main() {
use quack_rs::appender::{AppendError, Appender};
use libduckdb_sys::duckdb_connection;

unsafe fn demo(con: duckdb_connection) -> Result<(), AppendError> {
// SAFETY: `con` is a valid, open connection (e.g. from an entry point).
let appender = unsafe { Appender::new(con, None, c"measurements") }?;

for (sensor, reading) in [("a", 1.5_f64), ("b", 2.5)] {
    appender.row(|row| {
        row.append_str(sensor)?;
        row.append_f64(reading)
    })?;
}

appender.close()?;
Ok(())
}
fn live_connection() -> libduckdb_sys::duckdb_connection {
    std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
    let (mut db, mut con) = (std::ptr::null_mut(), std::ptr::null_mut());
    unsafe {
        assert_eq!(libduckdb_sys::duckdb_open(std::ptr::null(), &mut db), libduckdb_sys::DuckDBSuccess);
        assert_eq!(libduckdb_sys::duckdb_connect(db, &mut con), libduckdb_sys::DuckDBSuccess);
    }
    con
}
/// First column of the first row, as BIGINT; `None` for NULL.
fn query_i64(con: libduckdb_sys::duckdb_connection, sql: &str) -> Option<i64> {
    let mut result = unsafe { quack_rs::query::query(con, sql) }.unwrap();
    let chunk = result.next_chunk().unwrap().unwrap();
    let reader = unsafe { chunk.reader(0) };
    unsafe { reader.is_valid(0).then(|| reader.read_i64(0)) }
}
let con = live_connection();
unsafe { quack_rs::query::execute(con, "CREATE TABLE measurements (sensor VARCHAR, reading DOUBLE)") }.unwrap();
unsafe { demo(con) }.unwrap();
assert_eq!(query_i64(con, "SELECT count(*) FROM measurements"), Some(2));
assert_eq!(query_i64(con, "SELECT (sum(reading) * 10)::BIGINT FROM measurements"), Some(40));
}

append_str uses duckdb_append_varchar_length, so interior NUL bytes survive; the NUL-terminated duckdb_append_varchar would stop at the first one. append_str and append_bytes refuse a value longer than u32::MAX bytes, which DuckDB would silently truncate.

append_time and append_timestamp refuse, before calling DuckDB, a payload outside the range DuckDB's SQL produces (TIME 00:00:00–24:00:00; a TIMESTAMP from 290309-12-22 (BC), plus -infinity). DuckDB stores such a value unchecked, and reading the row back later fails or crashes.

A chunk at a time

append_chunk takes a whole DataChunk whose column types match the appender's active columns. It makes fewer FFI calls than appending row by row and suits data that is already in vectors; it is refused while a row appended by hand is still open.

#![allow(unused)]
fn main() {
use quack_rs::appender::{AppendError, Appender};
use quack_rs::data_chunk::DataChunk;
use libduckdb_sys::duckdb_connection;

unsafe fn load(con: duckdb_connection, chunks: &[DataChunk]) -> Result<(), AppendError> {
// SAFETY: `con` is a valid, open connection.
let appender = unsafe { Appender::new(con, None, c"events") }?;
for chunk in chunks {
    appender.append_chunk(chunk)?;
}
appender.close()?;
Ok(())
}
}

Pass a schema (or a fully-qualified catalog + schema) when the default schema is not what you want:

#![allow(unused)]
fn main() {
use quack_rs::appender::{AppendError, Appender};
use libduckdb_sys::duckdb_connection;
unsafe fn demo(con: duckdb_connection) -> Result<(), AppendError> {
let a = unsafe { Appender::new(con, Some(c"main"), c"events") }?;
let b = unsafe { Appender::with_catalog(con, Some(c"mydb"), Some(c"main"), c"events") }?;
let _ = (a, b);
Ok(())
}
}

Appending a subset of columns

add_column narrows the active column list; the omitted columns take their DEFAULT (or NULL). Both add_column and clear_columns flush every row appended so far.

#![allow(unused)]
fn main() {
use quack_rs::appender::{AppendError, Appender};
unsafe fn demo(appender: &Appender) -> Result<(), AppendError> {
appender.add_column(c"id")?;              // now only `id` is expected
appender.row(|row| row.append_i32(7))?;
appender.clear_columns()?;                // back to every column
Ok(())
}
}

Use TableDescription::column_has_default to find out whether a column has a default before relying on one. append_default() fails for a default that is not a constant, such as nextval('seq') or now(): DuckDB's appender evaluates defaults once, when it is created.

Errors arrive late, and invalidate the batch

Appended rows are buffered. A constraint violation therefore surfaces at flush or close, not at the append_* call that caused it, and it invalidates every buffered row.

With duckdb-1-5, clear discards the offending buffer so you can carry on without re-appending rows that were already committed:

#![allow(unused)]
fn main() {
use quack_rs::appender::Appender;
fn demo(appender: &Appender) {
if let Err(err) = appender.flush() {
    eprintln!("flush failed: {err}");
    let _ = appender.clear(); // drop the offending buffered rows
}
}
}

A row that fails half-way loses the batch

DuckDB counts the values of the current row and cannot take one back. If a row closure fails or panics after its first value went in, the half-written row can be neither finished nor dropped, and DuckDB's close then returns success while writing nothing: every row buffered since the last flush is gone. (DuckDB also flushes by itself each time 204,800 rows accumulate; rows written by such a flush are safe.)

quack-rs does not let that pass silently. The appender becomes poisoned: every later row, append, end_row, flush and close returns an error saying how many buffered rows were not written. With duckdb-1-5, clear() discards them and makes the appender usable again; without it, create a new appender. close() with a row that was started but not ended is an error too (finish the row and close again).

A value that fails as the first of its row loses nothing, and when you append by hand you can retry a rejected value in the same column. If losing a batch is not acceptable, flush() at the points you can afford to go back to.

After a successful close() the appender refuses all further work.

Row order and schema changes

• Row-at-a-time rows wait in their own buffer until a full chunk (2,048 rows) accumulates, while append_chunk adds its rows to the table-bound buffer directly, so a chunk lands ahead of rows appended before it that are still buffered. Flush first if insertion order matters.
• Buffered rows are written by column position at flush time. If another connection drops a column and adds one in between, a value lands in the new column with no error.

API

¹ Requires the duckdb-1-5 feature flag.

Every fallible method returns Result<_, AppendError>. AppendError is ErrorData (message and machine-readable category) when duckdb-1-5 is enabled, and ExtensionError (message only) otherwise — enabling the feature upgrades the error type in place without changing any method's shape.

Safety

new and with_catalog are unsafe: you must pass a valid, open duckdb_connection (such as the one provided to your extension's entry point).

Both return Result for a reason: DuckDB's duckdb_append_* functions do not check whether the appender was created successfully before dereferencing it, so an appender whose creation failed must never be used. A failed create returns Err and no Appender, so such an appender cannot be reached.

Drop

Dropping an Appender closes (and so flushes) it, but the result is ignored — DuckDB's own header notes that after destruction "it is no longer possible to obtain the specific error message". Call close() explicitly whenever the outcome matters.

Related chapters

• Reading & Writing Vectors — building the DataChunks you append
• Table Metadata — column names and DEFAULTs
• Structured Errors — the ErrorData returned with duckdb-1-5
• The Entry Point — where you obtain a connection

Table Metadata

TableDescription reads the column metadata of an existing DuckDB table from inside your extension: column names, whether a column has a DEFAULT, and, with duckdb-1-5, the column count and types. Replacement scans, table functions and copy functions use it to inspect a table before deciding what to do.

No feature flag required for creating a description or reading column names and defaults: duckdb_table_description_* has been in the frozen stable prefix of the extension API (slots 292–297) since v1.2.0. Two accessors, column_count and column_type, were added in DuckDB 1.5 in the unstable region and need duckdb-1-5.

#![allow(unused)]
fn main() {
use quack_rs::table_description::TableDescription;
use libduckdb_sys::duckdb_connection;

unsafe fn demo(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
// SAFETY: `con` is a valid, open connection.
let desc = unsafe { TableDescription::create(con, "main", "events") }?;

assert_eq!(desc.column_name(0).as_deref(), Some("id"));
assert_eq!(desc.column_has_default(0), Some(false));
Ok(())
}
}

with_catalog addresses a table in another catalog, and takes None to mean "the default" for either the catalog or the schema:

#![allow(unused)]
fn main() {
use quack_rs::table_description::TableDescription;
use libduckdb_sys::duckdb_connection;
unsafe fn demo(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
let desc = unsafe { TableDescription::with_catalog(con, Some("mydb"), None, "events") }?;
let _ = desc;
Ok(())
}
}

API

¹ Requires the duckdb-1-5 feature flag.

Out-of-range indices return None rather than panicking, so a description can be walked without knowing the width up front when duckdb-1-5 is off.

Related chapters

• Bulk Appender — append_default fills a column without a DEFAULT with NULL, and fails for a DEFAULT that is not a constant (nextval(...), random()), which column_has_default reports as true
• Type System — what a LogicalType describes

Structured Errors

Requires the duckdb-1-5 feature flag (DuckDB 1.5.0+).

ErrorData is an RAII wrapper around DuckDB's duckdb_error_data handle, the structured error type that several DuckDB 1.5 C API functions return. Unlike a bare error string, an ErrorData carries both a human-readable message and a machine-readable category (DuckDbErrorType), so your extension can branch on the kind of failure (for example, distinguishing Io from OutOfMemory).

Expression::fold, the virtual file system, the Arrow bridge and the appender all report failures as an ErrorData.

Inspecting an error

#![allow(unused)]
fn main() {
use quack_rs::error_data::{DuckDbErrorType, ErrorData};

fn handle(err: ErrorData) {
if err.has_error() {
    match err.error_type() {
        DuckDbErrorType::Io => eprintln!("I/O failure"),
        DuckDbErrorType::OutOfMemory => eprintln!("out of memory"),
        other => eprintln!("{other:?}: {}", err.message().unwrap_or_default()),
    }
}
}
}

Constructing an error

Build a structured error to hand back to DuckDB (for example from a callback):

#![allow(unused)]
fn main() {
// ErrorData is a DuckDB object: fill the dispatch table first.
std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
use quack_rs::error_data::{DuckDbErrorType, ErrorData};

let err = ErrorData::new(DuckDbErrorType::InvalidInput, "row index out of range");
assert!(err.has_error());
assert_eq!(err.error_type(), DuckDbErrorType::InvalidInput);
}

Propagating with ?

into_extension_error converts an ErrorData into the SDK's ExtensionError, so a structured DuckDB error can flow through the ? operator in your registration or callback logic:

#![allow(unused)]
fn main() {
use quack_rs::error::ExtensionError;
use quack_rs::file_system::{FileOpenOptions, FileSystem};
use quack_rs::client_context::ClientContext;
use quack_rs::error_data::ErrorData;

fn read_header(ctx: &ClientContext) -> Result<(), ExtensionError> {
let fs = FileSystem::from_client_context(ctx)
    .ok_or_else(|| ExtensionError::new("no file system"))?;
let handle = fs
    .open(c"data.bin", &FileOpenOptions::read_only())
    .map_err(ErrorData::into_extension_error)?;
let _ = handle;
Ok(())
}
}

API

DuckDbErrorType is a #[non_exhaustive] enum mirroring duckdb_error_type (Io, OutOfMemory, Conversion, Catalog, Constraint, Permission, …). Unknown or future categories map to DuckDbErrorType::Invalid.

UTF-8 validation

The free function check_valid_utf8 exposes DuckDB's own UTF-8 validator. Its rules match Rust's exactly: it accepts every Unicode scalar value and rejects surrogates, overlong forms, code points above U+10FFFF, truncated sequences and stray continuation bytes, just as std::str::from_utf8 does. Use it when you want DuckDB's structured ErrorData for the failure; for a yes/no answer, std::str::from_utf8 is equivalent and needs no database:

#![allow(unused)]
fn main() {
// ErrorData is a DuckDB object: fill the dispatch table first.
std::mem::forget(quack_rs::testing::InMemoryDb::open().unwrap());
use quack_rs::error_data::check_valid_utf8;

fn demo(bytes: &[u8]) {
match check_valid_utf8(bytes) {
    Ok(()) => { /* safe to pass to DuckDB */ }
    Err(err) => eprintln!("invalid UTF-8: {}", err.message().unwrap_or_default()),
}
}
assert!(check_valid_utf8("héllo".as_bytes()).is_ok());
for bad in [&b"\xff"[..], b"\xed\xa0\x80", b"\xc0\xaf", b"\xf4\x90\x80\x80", b"\xe2\x82"] {
    assert!(check_valid_utf8(bad).is_err());
    assert!(std::str::from_utf8(bad).is_err());
}
}

Ownership

ErrorData calls duckdb_destroy_error_data on drop. An ErrorData received from a fallible 1.5 API owns its handle: let it drop, or call into_extension_error() / into_raw() to move the data out.

Related modules

• Bound Expressions — Expression::fold returns ErrorData
• Virtual File System — file operations return ErrorData
• Arrow Interop — the conversion functions return ErrorData
• Bulk Appender — Appender::error_data returns ErrorData
• Error Handling — the SDK's primary ExtensionError type

Bound Expressions

Requires the duckdb-1-5 feature flag (DuckDB 1.5.0+).

Expression is an RAII wrapper around DuckDB's duckdb_expression handle. You obtain one from a scalar function's bind callback via ScalarBindInfo::argument, which lets the bind phase inspect each argument's static type and — when the argument is a constant — fold it to a concrete Value.

Use it for scalar functions whose behaviour depends on a constant argument (a format string, a precision, a regex) that should be validated or pre-computed once at bind time rather than on every row.

Folding a constant argument at bind time

#![allow(unused)]
fn main() {
use quack_rs::scalar::{RawScalarBindInfo, ScalarBindInfo};

unsafe extern "C" fn my_bind(info: RawScalarBindInfo) {
    let bind = unsafe { ScalarBindInfo::new(info) };

    if let Some(arg) = unsafe { bind.argument(0) } {
        // Inspect the argument's static return type.
        let _ty = arg.return_type();

        // If the argument is constant, evaluate it once here instead of
        // recomputing it for every row in the execute callback.
        if arg.is_foldable() {
            let ctx = unsafe { bind.get_client_context() };
            match arg.fold(&ctx) {
                Ok(value) => {
                    // Stash `value` as bind data for the execute phase.
                    let _ = value;
                }
                Err(err) => bind.set_error(&err.message().unwrap_or_default()),
            }
        }
    }
}
}

API