Skip to main content

Crate quack_rs

Crate quack_rs 

Source
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_point module
  • 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 DuckDB Rust 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:

ModulePurpose
abiDuckDB C extension API layout verification (stable vs unstable region)
callbackPanic-safe extern "C" callback wrapper macros for every callback kind
chunk_writerAuto-sizing chunk writer for table scan callbacks (auto set_size on drop)
data_chunkErgonomic wrapper for DuckDB data chunks
entry_pointHelper for the correct {name}_init_c_api C entry point
connectionConnection facade + Registrar trait for version-agnostic registration
aggregateBuilders for aggregate function registration
scalarBuilder for scalar function registration
castBuilder for custom type cast functions
tableBuilders for table function registration (raw TableFunctionBuilder + closure-based TypedTableFunctionBuilder<S>)
replacement_scanSELECT * FROM 'file.xyz' replacement scan registration
sql_macroSQL macro registration (CREATE MACRO) — no FFI callbacks
vectorSafe helpers for reading/writing DuckDB data vectors
vector::complexSTRUCT / LIST / MAP / ARRAY vector access (child vectors, offsets)
vector::struct_readerBatched StructReader for STRUCT input vectors
vector::opsWhole-vector operations driven by a selection vector (duckdb-1-5 feature)
vector::struct_writerBatched StructWriter for STRUCT output vectors
typesDuckDB type system wrappers (TypeId, LogicalType)
datetimeDATE/TIME/TIMESTAMP calendar conversions, HUGEINT/DECIMAL helpers
intervalINTERVAL → microseconds conversion with overflow checking
errorExtensionError for FFI error propagation
configRAII wrapper for DuckDB database configuration
valueRAII wrapper for DuckDB values with typed extraction
tlsType-erased TLS configuration provider for HTTP-capable extensions
warningStructured security warning API (ExtensionWarning, WarningCollector)
secretsSecrets manager bridge trait (SecretsManager, SecretEntry)
validateCommunity extension compliance validators
validate::description_ymlParse and validate description.yml metadata
scaffoldProject generator for new extensions (no C++ glue needed)
testingTest utilities: AggregateTestHarness, mock vectors (MockVectorReader, MockVectorWriter), MockRegistrar, and InMemoryDb (bundled-test feature)
queryRunning SQL from an extension (QueryResult, PreparedStatement, OwnedConnection)
preludeConvenience re-exports of the most commonly used items
appenderBulk row appender (Appender)
table_descriptionTable metadata (column names, DEFAULTs)
arrowArrow C Data Interface bridge, no arrow crate dependency (duckdb-1-5-4 feature)
catalogCatalog entry lookup (duckdb-1-5 feature)
client_contextClient context access (duckdb-1-5 feature)
config_optionExtension-defined configuration options (duckdb-1-5 feature)
copy_functionCustom COPY TO handlers and COPY … FROM readers (duckdb-1-5 feature)
error_dataStructured error type + UTF-8 validation (duckdb-1-5 feature)
expressionBound expression inspection / constant folding (duckdb-1-5 feature)
file_systemDuckDB virtual file system access (duckdb-1-5 feature)
instance_cacheShared database instance cache (duckdb-1-5 feature)
selection_vectorZero-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 fn states what the caller must guarantee under # Safety; a trait’s unsafe methods state it once, on the trait.
  • Every unsafe block inside a safe function carries a // SAFETY: comment, because there the crate — not the caller — is asserting the invariant.
  • Every unsafe block inside an unsafe fn carries one too, even when it only forwards the function’s own contract (unsafe_op_in_unsafe_fn is 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

  1. Thin wrapper: every abstraction must pay for itself in reduced boilerplate or improved safety. When in doubt, prefer simplicity.
  2. No panics across FFI: the entry point macros, the *_callback! macros in callback, the closure-based builders and FfiState’s callbacks run user code under catch_unwind, so a panic becomes a SQL error. A raw unsafe extern "C" fn that you pass to a builder yourself is installed as written, with no guard; define it with the matching *_callback! macro or wrap its body in catch_ffi_panic. Library code panics only where a # Panics section says so.
  3. Bounded version range: libduckdb-sys uses >=1.4.4, <1.20100, and the crate supports DuckDB 1.4.4 through 2.0.x. libduckdb-sys numbers DuckDB 2.0.0 1.20000.0 (published 2026-10-22) and DuckDB 2.1.0 will be 1.20100.0, so the bound admits the 2.0 bindings and stops before 2.1. The upper bound is deliberate: see CONTRIBUTING.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 latest DuckDB release.
  4. 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
DuckDB C Extension API ABI compatibility checking.
aggregate
Builders for registering DuckDB aggregate functions.
appender
Bulk data appending.
arrow
Arrow C Data Interface bridge (duckdb-1-5-4 feature).
callback
Panic-safe callback wrapper macros for DuckDB extension callbacks.
cast
Builder for registering DuckDB custom cast functions.
catalog
Catalog entry lookup (DuckDB 1.5.0+).
chunk_writer
Auto-sizing chunk writer for table function scan callbacks.
client_context
Client context access (DuckDB 1.5.0+).
config
RAII wrapper for DuckDB database configuration.
config_option
Extension-defined configuration options (DuckDB 1.5.0+).
connection
Connection — version-agnostic extension registration facade.
copy_function
Copy function registration (DuckDB 1.5.0+).
data_chunk
Ergonomic wrapper around DuckDB data chunks.
datetime
Calendar conversions for DuckDB’s temporal types.
entry_point
Extension entry point helper.
error
Error types for DuckDB extension FFI error propagation.
error_data
Structured error data (DuckDB 1.5.0+).
expression
Bound expressions (DuckDB 1.5.0+).
file_system
File system access (DuckDB 1.5.0+).
instance_cache
Database instance cache (DuckDB 1.5.0+).
interval
DuckDB INTERVAL type conversion utilities.
prelude
Convenience re-exports for the most commonly used quack-rs items.
query
Running SQL from inside an extension.
replacement_scan
Builder for registering DuckDB replacement scans.
scaffold
Project scaffolding for DuckDB Rust extensions.
scalar
Builder for registering DuckDB scalar functions.
secrets
Credential handling for extensions.
selection_vector
Selection vectors (DuckDB 1.5.0+).
sql_macro
SQL macro registration for DuckDB extensions.
table
Builder for registering DuckDB table functions.
table_description
Table description metadata.
testing
Test utilities for DuckDB extension development.
tls
Type-erased TLS configuration provider for HTTP-capable extensions.
types
DuckDB type system wrappers.
validate
Validation utilities for DuckDB community extension compliance.
value
RAII wrapper around DuckDB values (duckdb_value).
vector
Safe helpers for reading from and writing to DuckDB data 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 ... TO bind callback so a panic becomes a DuckDB error.
copy_finalize_callback
Wraps a COPY ... TO finalize callback so a panic becomes a DuckDB error.
copy_global_init_callback
Wraps a COPY ... TO global init callback so a panic becomes a DuckDB error.
copy_sink_callback
Wraps a COPY ... TO sink callback so a panic becomes a DuckDB error.
entry_point
Generates the #[unsafe(no_mangle)] unsafe extern "C" entry point for a DuckDB extension.
entry_point_v2
Generates the #[unsafe(no_mangle)] unsafe extern "C" entry point using the version-agnostic Connection facade.
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 DuckDB C 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-5 features with: --abi-type C_STRUCT --duckdb-version v1.5.6.