/ˈkwækərz/ · rhymes with crackers · inspired by DuckDB
Write DuckDB loadable extensions in Rust, with no C or C++ to write. Pre-1.0: the API changes between minor releases, and audits keep finding defects. Read Status before you depend on it.
quack-rs wraps DuckDB's C Extension API
so that you can write a loadable extension entirely in Rust. Your repository
holds Rust only: no C or C++ source, no CMake file, no glue layer of your own
between your functions and the C API. The build still runs other people's C and
tools: dependencies of the DuckDB bindings may compile C, the bundled-test*
features compile C++ or C, and the community-extension flow needs Python and git
(Installation
has the list).
- Every function kind the C API can register: scalar, aggregate, table, cast, copy and replacement scan functions, plus SQL macros.
- Scalar functions as safe closures.
ScalarFunctionBuilder::map1and its siblings take a plain Rust closure, derive the SQL types from its signature, return NULL for NULL input, and turn a panic into a SQL error. - Guards against documented FFI pitfalls. Most of the 38 pitfalls in
LESSONS.mdare prevented by a wrapper, such as NULL output that is silently lost, a boolean read that is undefined behaviour, or a double free in an aggregate destructor. The rest are documented. - A panic in a guarded callback becomes a SQL error. The entry-point macros,
the closure-based builders and the
*_callback!macros run your code undercatch_unwind. A rawunsafe extern "C" fnthat you pass to a builder yourself is installed unguarded; see Installation. - Aggregate logic you can test without DuckDB.
AggregateTestHarnessruns the update, combine and finalize steps in plain Rust. - A load-time ABI check. The extension compares the C API layout it was built against with the one the running DuckDB hands it and, by default, refuses to load on a mismatch.
- Community-extension tooling. A project scaffold, runtime validators for
description.yml, names, versions and platforms, and anappend_metadatabinary that writes the footer DuckDB requires.
1. Cargo.toml. panic = "unwind" is required: under panic = "abort"
nothing can be caught, and a panic kills the user's DuckDB process.
[package]
name = "my_extension"
version = "0.1.0"
edition = "2021"
# With resolver 3, Cargo picks versions that build on this.
rust-version = "1.86"
resolver = "3"
[lib]
# Must match the extension name (Pitfall P1).
name = "my_extension"
crate-type = ["cdylib", "rlib"]
[dependencies]
quack-rs = "0.20"
[dependencies.libduckdb-sys]
version = ">=1.4.4, <1.20100"
default-features = false
features = ["loadable-extension"]
[profile.release]
panic = "unwind" # required
lto = true # the rest are recommended
opt-level = 3
codegen-units = 1
strip = true2. src/lib.rs.
use libduckdb_sys::duckdb_connection;
use quack_rs::entry_point;
use quack_rs::error::ExtensionError;
use quack_rs::scalar::ScalarFunctionBuilder;
fn register(
con: duckdb_connection,
) -> Result<(), ExtensionError> {
// Types come from the closure signatures. A NULL
// argument gives a NULL result without calling the
// closure. `try_map1` lets the closure fail: a plain
// `x * 2` wraps on overflow in a release build, and
// `Err` becomes a SQL error instead.
let double_it = ScalarFunctionBuilder::try_map1(
"double_it",
|x: i64| x.checked_mul(2).ok_or("double_it: overflow"),
)?;
let shout = ScalarFunctionBuilder::map1_str(
"shout",
|s: &str| s.to_uppercase(),
)?;
// SAFETY: `con` is the live connection DuckDB passed to
// the entry point.
unsafe {
double_it.register(con)?;
shout.register(con)?;
}
Ok(())
}
// The symbol must be `<extension name>_init_c_api`.
entry_point!(my_extension_init_c_api, |con| register(con));3. Build, stamp and load. DuckDB refuses to LOAD a bare shared library,
so append the metadata footer first. --duckdb-version is the C API version
(v1.2.0), not a DuckDB release (Pitfall P2). Installing append_metadata
needs Rust 1.88 or newer, because cargo install resolves the newest
libduckdb-sys, which requires it; use cargo +stable install if your
project pins an older toolchain. Your extension itself still builds on 1.86.
cargo build --release
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
duckdb -unsigned -c "LOAD './my_extension.duckdb_extension';
SELECT double_it(21), shout('hello');"
# ┌───────────────┬────────────────┐
# │ double_it(21) │ shout('hello') │
# │ int64 │ varchar │
# ├───────────────┼────────────────┤
# │ 42 │ HELLO │
# └───────────────┴────────────────┘On macOS the library is libmy_extension.dylib (platform osx_arm64 or
osx_amd64; osx_amd64 is opt-in in extension-ci-tools for DuckDB 2.0, and
DuckDB 2.1 drops it); on Windows it is my_extension.dll (windows_amd64).
To start a community extension from scratch, the
project scaffold generates
the Cargo.toml, entry point, description.yml, SQLLogicTest skeleton and CI
workflow. Your First Extension
continues with aggregates and table functions.
DuckDB 2.0 has two C extension APIs, and the Rust options divide along that
line. Checked against the published sources of duckdb and
duckdb-loadable-macros 1.20000.1, duckdb-neo 0.20000.1 and the
extension-template-rs repository's main on 2026-10-29:
| quack-rs | duckdb + macros |
template + duckdb-neo |
|
|---|---|---|---|
| C API | v1, stable | v1 by default; v2 behind the macros' neo feature |
v2, unstable |
| Binary loads in | every DuckDB 1.4.4 to 2.0.x (default features; tested to 2.0.0) | as quack-rs: set by the C API v1 stamp | the one DuckDB release it was built for (the template's Makefile says so) |
| Wraps | scalar, aggregate, table, cast, copy, replacement scan; macros | scalar and table functions | scalar, aggregate, table, cast, copy, macro and pragma functions; scans, types, options, log sinks |
| Status | pre-1.0 (see Status) | the duckdb crate |
duckdb-neo calls itself experimental |
Use duckdb-neo if you target DuckDB 2.0 and later only and want upstream's
wrapper, or need what only the v2 API offers (pragma functions, for one).
Use quack-rs if one binary has to load across DuckDB releases, or if you need
aggregate, cast, copy or replacement-scan functions on the stable API.
quack-rs does not generate the C API v2 entry point, and will not until DuckDB
declares part of that API stable.
quack-rs is pre-1.0. Judge it against your own requirements; the record so
far:
- The API still changes. A minor release before 1.0 can break it; each lists
its breaking changes and migration notes in
CHANGELOG.md. - Audits keep finding real defects. The 0.16.0 release, which came out of a
review, fixed defects in earlier releases, including two heap-corruption
paths. The 0.18.0 audits fixed further soundness holes in the safe API,
process aborts and wrong answers, and found a serious defect in unreleased
code before publication: aggregate functions returned wrong results in release
builds with Cargo's default profile.
AUDIT.mdrecords each audit, what it found, and whether each fix was reproduced against a real DuckDB or derived from DuckDB's source. Use 0.18.0 or later. Earlier releases still have the soundness holes in the safe API, and 0.7.0 through 0.15.0 can corrupt the heap when theduckdb-1-5features are used. - Maintenance. One maintainer (
GOVERNANCE.md).SECURITY.mdlists the release lines that receive fixes. - Some limits are DuckDB's. Defects in DuckDB's C API that quack-rs can only document or work around are listed under Known Limitations.
- What CI checks. Every pull request runs the full test suite against a real DuckDB (1.5.6) on Linux, macOS and Windows; the suite again against DuckDB 1.4.4, 1.4.5, 1.5.0, 1.5.3, 1.5.4 and 1.5.5; the unit tests on wasm32; the suite against DuckDB 2.0.0 with the DuckDB 2.0 bindings; AddressSanitizer; and a load test of a built extension into DuckDB 1.4.4, 1.5.0, 1.5.5, 1.5.6, 2.0.0 and the latest release.
If you ship an extension built on it, test it end to end against every DuckDB release you support.
- DuckDB: with the default features, 1.4.4 through 2.0.x (the tests ran
against 2.0.0, the newest release when 0.20.0 was published). With a
duckdb-1-5*feature, only the releases whose C API layout quack-rs has verified: 1.5.6 and 2.0.0. Any other release, a future 2.0.1 included, is refused atLOAD(see below). libduckdb-sys:>=1.4.4, <1.20100. That covers the bindings for every DuckDB release above, 1.4.4 through 1.20000.x (the DuckDB 2.0 bindings, first published 2026-10-22). 1.20000.x needs Rust 1.88; on 1.88 or newercargo updateselects it, and an older toolchain with MSRV-aware resolution stays on 1.10506.x (DuckDB 1.5.6). The upper bound keeps out the DuckDB 2.1 bindings (1.20100.x) until a quack-rs release has been tested against them (why).- Rust (MSRV): 1.86.0.
DuckDB 2.0.0 (2026-10-21) is a long-term support release, supported until at least October 2027; DuckDB supports 1.4 until late November 2026 and 1.5 until March 2027.
With the default features, one extension binary loads into every DuckDB release
from 1.4.4 through 2.0.x, because it is stamped with C API version v1.2.0.
DuckDB 1.4.4 to 1.5.5 declare that version; 1.5.6 and 2.0.0 declare v1.5.6
and still load v1.2.0 extensions. The duckdb-1-5* features use the part of
DuckDB's C API whose layout changed between releases up to 1.5.5 (DuckDB
labels C API v1.5.6 stable, with the caveat below). Build such an extension against the 1.5.6
bindings and stamp it C_STRUCT with C API v1.5.6; it then loads into DuckDB
1.5.6 and 2.0.0. quack-rs has verified that layout for DuckDB 1.5.2 to 1.5.6 and
2.0.0 only, and DuckDB's 2.0.0 header says the API is guaranteed for that exact
release (2.0.0 added two slots to the range that 1.5.6 declared stable). So under
the default Strict policy such an extension refuses to load into a release
quack-rs has not listed, with an error that says how to fix it. When one appears
(DuckDB 2.0.1, for example), either rebuild with
QUACK_RS_TARGET_DUCKDB_VERSION set to that release, once you have checked it,
or move to a quack-rs release that lists it; or stay on the default features,
which are not affected. See
ABI Compatibility before you enable one.
All features are off by default. The default build uses only the stable C API.
| Feature | Requires | Enables |
|---|---|---|
duckdb-1-5 |
libduckdb-sys >= 1.10500.0 (DuckDB 1.5.0) |
Wrappers for the C API added in DuckDB 1.5, among them scalar bind/init and local state, config options, copy functions, catalog, client context, structured errors, bound expressions, the virtual file system, selection vectors and the instance cache |
duckdb-1-5-3 |
libduckdb-sys >= 1.10503.0 (DuckDB 1.5.3); implies duckdb-1-5 |
TypeId::Variant and TypeId::Geometry |
duckdb-1-5-4 |
libduckdb-sys >= 1.10504.0; implies duckdb-1-5-3; a DuckDB 1.5.0+ engine at run time |
The arrow module (Arrow C Data Interface bridge, no arrow crate dependency) |
bundled-test |
A C++ toolchain (compiles DuckDB from source, about 5–10 minutes cold) | testing::InMemoryDb, a real in-memory DuckDB for SQL-level tests in cargo test |
bundled-test-prebuilt |
A pre-built libduckdb: DUCKDB_DOWNLOAD_LIB=1 or DUCKDB_LIB_DIR (an extracted 1.x libduckdb-<platform>.zip or 2.0 duckdb-shared-libs-<platform>.tar.gz); header discovery needs libduckdb-sys >= 1.10503 (older: set DUCKDB_INCLUDE_DIR) |
The same InMemoryDb, linked against the pre-built library |
Enable the two test features as dev-dependency features only. The
duckdb-1-5-4 floor comes from the bindings: libduckdb-sys shipped the Arrow
struct layouts first in 1.10504.0, although the DuckDB functions exist from
1.4.4.
- The book, quack-rs.com: guides from the
first extension to community submission. The site root is the latest
release;
https://quack-rs.com/vX.Y/is each release line (for example /v0.19/), and /dev/ is themainbranch. - API reference: docs.rs/quack-rs. The crate root lists every module.
- Pitfall Catalog and
LESSONS.md: all 38 known pitfalls (L1–L21, P1–P17), with symptom, cause and fix. examples/hello-ext: one extension with scalar, aggregate, table, cast, macro and replacement-scan functions, checked in CI. It uses raw callbacks, which are not panic-guarded: read it for the C API calls, do not copy it as a template.- Community Extensions:
description.yml, naming, versioning, platforms and submission. - Testing Guide: mocks,
AggregateTestHarnessandInMemoryDb. docs/architecture.md: module layout, design principles and the architecture decision records.CHANGELOG.md: every release, with breaking changes and migration notes. The latest is 0.20.0 (2026-10-30).CONTRIBUTING.md: development setup, quality gates and the test strategy.SECURITY.md: supported versions and how to report a vulnerability.
- A bug, or something the book does not answer: GitHub issues. The bug report template asks for the DuckDB version that fails and the footer stamp.
LOADfails before your code runs: the FAQ lists the messages DuckDB gives and what causes each.- A vulnerability: report it privately, as
SECURITY.mddescribes.
MIT — see LICENSE.
DuckDB is a trademark of the DuckDB Foundation. quack-rs is an independent
community project; it is not affiliated with or endorsed by the DuckDB Foundation
or DuckDB Labs.