Expand description
A Rust SDK for building DuckDB loadable extensions on the DuckDB C Extension API.
§Overview
quack-rs encapsulates the hard-won FFI knowledge required to build DuckDB
community extensions in Rust. It provides:
- A correct, panic-free entry point helper via the
entry_pointmodule - Type-safe builders for registering aggregate functions (
aggregate) - Safe vector reading and writing helpers (
vector) - A generic
FfiState<T>that eliminates raw pointer management - Documentation of every known
DuckDBRust FFI pitfall, with API designs that prevent most of them
§Quick Start
// In your extension's src/lib.rs:
use quack_rs::entry_point;
use quack_rs::error::ExtensionError;
fn register(_con: libduckdb_sys::duckdb_connection) -> Result<(), ExtensionError> {
// register_my_function(con)?;
Ok(())
}
// Generates the `#[unsafe(no_mangle)] extern "C"` entry point. Pass the full symbol
// name DuckDB looks up: `{extension_name}_init_c_api`.
entry_point!(my_extension_init_c_api, |con| register(con));To write the entry point by hand instead, call
init_extension directly; the
entry_point module documentation shows how.
§Architecture
The SDK is organized into focused modules:
| Module | Purpose |
|---|---|
abi | DuckDB C extension API layout verification (stable vs unstable region) |
callback | Panic-safe extern "C" callback wrapper macros for every callback kind |
chunk_writer | Auto-sizing chunk writer for table scan callbacks (auto set_size on drop) |
data_chunk | Ergonomic wrapper for DuckDB data chunks |
entry_point | Helper for the correct {name}_init_c_api C entry point |
connection | Connection facade + Registrar trait for version-agnostic registration |
aggregate | Builders for aggregate function registration |
scalar | Builder for scalar function registration |
cast | Builder for custom type cast functions |
table | Builders for table function registration (raw TableFunctionBuilder + closure-based TypedTableFunctionBuilder<S>) |
replacement_scan | SELECT * FROM 'file.xyz' replacement scan registration |
sql_macro | SQL macro registration (CREATE MACRO) — no FFI callbacks |
vector | Safe helpers for reading/writing DuckDB data vectors |
vector::complex | STRUCT / LIST / MAP / ARRAY vector access (child vectors, offsets) |
vector::struct_reader | Batched StructReader for STRUCT input vectors |
vector::ops | Whole-vector operations driven by a selection vector (duckdb-1-5 feature) |
vector::struct_writer | Batched StructWriter for STRUCT output vectors |
types | DuckDB type system wrappers (TypeId, LogicalType) |
datetime | DATE/TIME/TIMESTAMP calendar conversions, HUGEINT/DECIMAL helpers |
interval | INTERVAL → microseconds conversion with overflow checking |
error | ExtensionError for FFI error propagation |
config | RAII wrapper for DuckDB database configuration |
value | RAII wrapper for DuckDB values with typed extraction |
tls | Type-erased TLS configuration provider for HTTP-capable extensions |
warning | Structured security warning API (ExtensionWarning, WarningCollector) |
secrets | Secrets manager bridge trait (SecretsManager, SecretEntry) |
validate | Community extension compliance validators |
validate::description_yml | Parse and validate description.yml metadata |
scaffold | Project generator for new extensions (no C++ glue needed) |
testing | Test utilities: AggregateTestHarness, mock vectors (MockVectorReader, MockVectorWriter), MockRegistrar, and InMemoryDb (bundled-test feature) |
query | Running SQL from an extension (QueryResult, PreparedStatement, OwnedConnection) |
prelude | Convenience re-exports of the most commonly used items |
appender | Bulk row appender (Appender) |
table_description | Table metadata (column names, DEFAULTs) |
arrow | Arrow C Data Interface bridge, no arrow crate dependency (duckdb-1-5-4 feature) |
catalog | Catalog entry lookup (duckdb-1-5 feature) |
client_context | Client context access (duckdb-1-5 feature) |
config_option | Extension-defined configuration options (duckdb-1-5 feature) |
copy_function | Custom COPY TO handlers and COPY … FROM readers (duckdb-1-5 feature) |
error_data | Structured error type + UTF-8 validation (duckdb-1-5 feature) |
expression | Bound expression inspection / constant folding (duckdb-1-5 feature) |
file_system | DuckDB virtual file system access (duckdb-1-5 feature) |
instance_cache | Shared database instance cache (duckdb-1-5 feature) |
selection_vector | Zero-copy row-index selection vectors (duckdb-1-5 feature) |
§Safety
All unsafe code within this SDK is intended to be sound, and each block is
documented. It has been audited; AUDIT.md
records the passes and the defects they found. Extension authors
must write unsafe extern "C" callback functions (required by DuckDB’s C API),
but the SDK’s helpers minimize the surface area of unsafe code within those
callbacks.
The documentation convention is:
- Every
unsafe fnstates what the caller must guarantee under# Safety; a trait’sunsafemethods state it once, on the trait. - Every
unsafeblock inside a safe function carries a// SAFETY:comment, because there the crate — not the caller — is asserting the invariant. - Every
unsafeblock inside anunsafe fncarries one too, even when it only forwards the function’s own contract (unsafe_op_in_unsafe_fnis denied crate-wide, so the block is required syntax); the comment then says which clause of the contract it relies on.
clippy::undocumented_unsafe_blocks is enabled for library code and CI runs
clippy with -D warnings, so an unannotated block fails the build. Test
code is exempt: its invariants are the test’s own setup.
§Design Principles
- Thin wrapper: every abstraction must pay for itself in reduced boilerplate or improved safety. When in doubt, prefer simplicity.
- No panics across FFI: the entry point macros, the
*_callback!macros incallback, the closure-based builders andFfiState’s callbacks run user code undercatch_unwind, so a panic becomes a SQL error. A rawunsafe extern "C" fnthat you pass to a builder yourself is installed as written, with no guard; define it with the matching*_callback!macro or wrap its body incatch_ffi_panic. Library code panics only where a# Panicssection says so. - Bounded version range:
libduckdb-sysuses>=1.4.4, <1.20100, and the crate supportsDuckDB1.4.4 through 2.0.x.libduckdb-sysnumbersDuckDB2.0.01.20000.0(published 2026-10-22) andDuckDB2.1.0 will be1.20100.0, so the bound admits the 2.0 bindings and stops before 2.1. The upper bound is deliberate: seeCONTRIBUTING.md, “Releasing”. CI tests against 1.4.4, 1.4.5, 1.5.0, 1.5.3, 1.5.4, 1.5.5, 1.5.6 and 2.0.0, and loads an extension into 1.4.4, 1.5.0, 1.5.5, 1.5.6, 2.0.0 and the latestDuckDBrelease. - Testable business logic: state structs have zero FFI dependencies.
§Pitfalls
See LESSONS.md
for every known DuckDB Rust FFI pitfall, with symptoms, root causes, and fixes.
One of them, Pitfall L1 (COMBINE must propagate config fields), produces silently wrong results rather than an error:
DuckDB’s segment tree creates fresh target states with state_init —
T::default() for an FfiState<T> — and then
calls combine to merge source states into them. So your combine callback
MUST copy ALL configuration fields from source to target, not just
accumulated data: a field left at its Default value will be wrong at
finalize time, producing silently incorrect results.
See aggregate::callbacks::CombineFn for details.
Modules§
- abi
DuckDBC Extension API ABI compatibility checking.- aggregate
- Builders for registering
DuckDBaggregate functions. - appender
- Bulk data appending.
- arrow
- Arrow C Data Interface bridge (
duckdb-1-5-4feature). - callback
- Panic-safe callback wrapper macros for
DuckDBextension callbacks. - cast
- Builder for registering
DuckDBcustom cast functions. - catalog
- Catalog entry lookup (
DuckDB1.5.0+). - chunk_
writer - Auto-sizing chunk writer for table function scan callbacks.
- client_
context - Client context access (
DuckDB1.5.0+). - config
- RAII wrapper for
DuckDBdatabase configuration. - config_
option - Extension-defined configuration options (
DuckDB1.5.0+). - connection
Connection— version-agnostic extension registration facade.- copy_
function - Copy function registration (
DuckDB1.5.0+). - data_
chunk - Ergonomic wrapper around
DuckDBdata chunks. - datetime
- Calendar conversions for
DuckDB’s temporal types. - entry_
point - Extension entry point helper.
- error
- Error types for
DuckDBextension FFI error propagation. - error_
data - Structured error data (
DuckDB1.5.0+). - expression
- Bound expressions (
DuckDB1.5.0+). - file_
system - File system access (
DuckDB1.5.0+). - instance_
cache - Database instance cache (
DuckDB1.5.0+). - interval
DuckDBINTERVALtype conversion utilities.- prelude
- Convenience re-exports for the most commonly used
quack-rsitems. - query
- Running SQL from inside an extension.
- replacement_
scan - Builder for registering
DuckDBreplacement scans. - scaffold
- Project scaffolding for
DuckDBRust extensions. - scalar
- Builder for registering
DuckDBscalar functions. - secrets
- Credential handling for extensions.
- selection_
vector - Selection vectors (
DuckDB1.5.0+). - sql_
macro - SQL macro registration for
DuckDBextensions. - table
- Builder for registering
DuckDBtable functions. - table_
description - Table description metadata.
- testing
- Test utilities for
DuckDBextension development. - tls
- Type-erased TLS configuration provider for HTTP-capable extensions.
- types
DuckDBtype system wrappers.- validate
- Validation utilities for
DuckDBcommunity extension compliance. - value
- RAII wrapper around
DuckDBvalues (duckdb_value). - vector
- Safe helpers for reading from and writing to
DuckDBdata vectors. - warning
- Structured security warning API for extensions.
Macros§
- aggregate_
combine_ callback - Generates a panic-safe
unsafe extern "C"aggregate combine callback. - aggregate_
destroy_ callback - Generates a panic-safe
unsafe extern "C"aggregate state destructor. - aggregate_
finalize_ callback - Generates a panic-safe
unsafe extern "C"aggregate finalize callback. - aggregate_
update_ callback - Generates a panic-safe
unsafe extern "C"aggregate update callback. - cast_
callback - Generates a panic-safe
unsafe extern "C"cast callback. - copy_
bind_ callback - Wraps a
COPY ... TObind callback so a panic becomes aDuckDBerror. - copy_
finalize_ callback - Wraps a
COPY ... TOfinalize callback so a panic becomes aDuckDBerror. - copy_
global_ init_ callback - Wraps a
COPY ... TOglobal init callback so a panic becomes aDuckDBerror. - copy_
sink_ callback - Wraps a
COPY ... TOsink callback so a panic becomes aDuckDBerror. - entry_
point - Generates the
#[unsafe(no_mangle)] unsafe extern "C"entry point for aDuckDBextension. - entry_
point_ v2 - Generates the
#[unsafe(no_mangle)] unsafe extern "C"entry point using the version-agnosticConnectionfacade. - replacement_
scan_ callback - Generates a panic-safe
unsafe extern "C"replacement scan callback. - scalar_
bind_ callback - Generates a panic-safe
unsafe extern "C"scalar function bind callback (duckdb-1-5). - scalar_
callback - Generates a panic-safe
unsafe extern "C"scalar function callback. - scalar_
init_ callback - Generates a panic-safe
unsafe extern "C"scalar function init callback (duckdb-1-5). - table_
bind_ callback - Generates a panic-safe
unsafe extern "C"table function bind callback. - table_
init_ callback - Generates a panic-safe
unsafe extern "C"table function init callback. - table_
scan_ callback - Generates a panic-safe
unsafe extern "C"table function scan callback.
Constants§
- DUCKDB_
API_ VERSION - The
DuckDBC API version string required by [duckdb_rs_extension_api_init][libduckdb_sys::duckdb_rs_extension_api_init]. - DUCKDB_
API_ VERSION_ 1_ 5_ 6 - The C extension API version to stamp an extension that uses the
duckdb-1-5features with:--abi-type C_STRUCT --duckdb-version v1.5.6.