Installation
Add the dependency
[dependencies]
duckfn = "0.3.1"
# duckfn is built on these two crates. Add them explicitly as soon as you name
# their types or builders yourself — SqlMacro, Connection, LogicalType, Value, …
quack-rs = "0.19.0"
# `loadable-extension` dispatches through DuckDB's API table instead of linking
# libduckdb, which is what keeps a local DuckDB build unnecessary. Only the
# headers are used.
libduckdb-sys = { version = ">=1.4.4, <2", features = ["loadable-extension"] }
duckfn re-exports every macro from duckfn-macro, so
the snippet above is enough. Depend on duckfn-macro = "0.3.1" directly only if you want the
macros without the runtime.
Cargo features
| Feature | Enables | Requires |
|---|---|---|
duckdb-1-5 | Logical types added in DuckDB 1.5 — today TIME_NS (DuckTimeNs) — plus the copy-function types behind COPY ... TO. | libduckdb-sys headers from DuckDB 1.5 or newer. |
sql | Running SQL from a callback (duckfn::sql): one long-lived connection captured at registration, then execute / query — with parameter binding — and the result read back as dynamic columns. Uses only the stable C API, so it does not need duckdb-1-5: USE_UNSTABLE_C_API=0 with a v1.2.0 floor gives one binary for DuckDB 1.3 through 2.0. Has side effects: the connection lives as long as the process, take-ups serialize, and it deadlocks a runtime that executes DuckDB synchronously on one thread (DuckDB-Wasm's Node blocking bindings) — see Running SQL. | Nothing beyond the crate's own libduckdb-sys: every call stays in the stable C API region, which is what keeps the artifact loadable across releases. |
duck_vfs | Host file-system access (duckfn::duck_vfs): on top of that registration-time connection, DuckDB's VFS — so callbacks without a client context, aggregates above all, can read and write files, s3:// and http(s):// included. Implies owned-connection and duckdb-1-5. Has the same side effects as sql — see File system access. | Otherwise the same headers as duckdb-1-5. |
owned-connection | The base the two callback-side features share: one long-lived connection captured at registration. It exposes no API of its own — sql and duck_vfs are its two public faces and both depend on it, while it depends on neither. Name it directly only when you want to be explicit about that base. | Nothing. |
chrono | Conversions between the time wrapper types and chrono (DuckDate::to_naive_date and friends), so the epoch arithmetic lives in duckfn. | An optional chrono dependency, pulled in by this feature. |
uuid | Conversions between DuckUuid and uuid (to_uuid / from_uuid). | An optional uuid dependency. |
rust_decimal | Conversions between DuckDecimal<W, S> and rust_decimal; out-of-range and digit-losing values are errors. | An optional rust_decimal dependency. |
quack | The marker feature of this repository's example extension and CLI: it decides whether those two targets are compiled at all, never what they can do — that comes from naming capabilities. A dependent never needs it. | The example's capability list, which the build passes alongside it. |
Every feature is named after the module it exposes, and there is no aggregate switch: a
dependency names exactly what it uses. That is deliberate — an "everything on" feature says nothing
about what it costs (the two connection-carrying ones have side effects; duckdb-1-5 raises the C
API floor to v1.5.6, the layout DuckDB 1.5.6 and 2.0.0 share) and hides which capability a build
actually ended up with.
The three interop features are independent — enable only the crates you actually use:
duckfn = { version = "0.3.1", features = ["sql", "chrono", "uuid", "rust_decimal"] }
cli only adds clap and csv for the CLI binary, so it belongs in the crate that builds
src/bin/duckfn.rs — not in a dependency tree you want to keep lean.
loadable-extension is a feature of libduckdb-sys, not of duckfn, and it has to be enabled by
you.
The crate must build a cdylib
DuckDB loads an extension as a dynamic library:
[lib]
crate-type = ["cdylib"]
For a WebAssembly build the crate type changes instead to staticlib, because the final linking is
done by emcc. Leave the library alone and give the wasm target a crate root of its own — a
[[example]] carrying crate-type = ["staticlib"], as described in
Project structure.
Why no local DuckDB build
Normally a DuckDB extension is compiled against, and linked to, DuckDB itself. duckfn avoids that:
libduckdb-syswithloadable-extensioncompiles against DuckDB headers only — no library is linked.- DuckDB API calls go through a function pointer table that the host DuckDB fills in when it loads the extension and calls the entry point.
The consequence is a fast, dependency-free build (and cross-compilation that works), with one
trade-off: the extension must match the DuckDB version it is loaded into. A stable-region build
declares a C API floor and is accepted by every engine at or above it; one that uses the unstable
region declares v1.5.6, which DuckDB 1.5.6 and 2.0.0 accept. Loading a locally built extension
always needs -unsigned, because the file carries no signature.
Requirements
| Rust | 1.88 or newer (the crates use edition 2024; the floor comes from syn 3 in duckfn-macro, which needs rustc 1.88) |
| DuckDB | tested against v2.0.0 |
| Python 3 (optional) | only for the make configure / make test flow, which sets up the sqllogictest runner |
Where next
- Quick start — write, build and load an extension.
- Attributes — the full attribute and argument reference.
- Architecture — how the API table dispatch actually works.