duckfn

English | 简体中文

Write DuckDB extensions in plain Rust.

duckfn is a runtime framework for building DuckDB extensions on top of DuckDB's C Extension API. Together with duckfn-macro, a single attribute turns an ordinary Rust function into a DuckDB scalar, aggregate, table or copy function, a SQL macro, a replacement scan, a type cast, or a nested type — no C/C++ glue code, and no local DuckDB build required.

• Repository: https://github.com/shijianjs/duckfn
• Built on quack-rs · libduckdb-sys
• No unsafe to write: no unsafe fn, no raw pointers in your function bodies
• No DuckDB build required, no C/C++ code
• Attribute-driven registration through inventory
• Panic-safe: Rust panics become DuckDB errors instead of unwinding across the FFI boundary
• Host file system access: read and write through DuckDB's virtual file system (s3://, http(s):// with httpfs, in-memory) from any callback — aggregate functions included — plus one-line helpers such as duckfn::duck_vfs::read_string / write_string / append_string (duckdb-1-5 feature)
• Interop with other crates: the time wrapper types (DuckDate, DuckTimestamp / _S / _Ms / _Ns, DuckTimestampTz, DuckTime) convert to and from chrono, DuckUuid ↔ uuid, and DuckDecimal<W, S> ↔ rust_decimal (chrono / uuid / rust_decimal features) — out-of-range values, DuckDB's infinity and digit-losing conversions come back as errors, never as a panic or a silent truncation
• Works with DuckDB's official multi-platform extension CI

Status: early / experimental. APIs may change before 1.0.

Installation

[dependencies]
duckfn = "0.0.8"

# duckfn itself is built on these two crates; add them explicitly when you use
# their types or builders directly.
quack-rs = "0.16.0"
# `loadable-extension` dispatches through DuckDB's API table instead of linking
# libduckdb, which is what keeps a local DuckDB build unnecessary.
# (headers only — no linked library)
libduckdb-sys = { version = ">=1.4.4, <2", features = ["loadable-extension"] }

If you prefer the macros without the runtime, depend on duckfn-macro directly; otherwise the macros are re-exported by duckfn and no extra dependency is needed.

duckfn has four optional features. duckdb-1-5 enables what DuckDB's 1.5 C API added: the logical types from DuckDB 1.5 (currently TIME_NS), copy functions, and host file-system access. The other three are interop and independent of each other: chrono converts the time wrapper types to and from chrono, uuid converts DuckUuid to and from uuid, and rust_decimal converts DuckDecimal<W, S> to and from rust_decimal — so the epoch / 128-bit / scaled-integer arithmetic lives in duckfn rather than in every extension:

duckfn = { version = "0.0.8", features = ["duckdb-1-5", "chrono", "uuid", "rust_decimal"] }

Quick start

use duckfn::{duck_error, duck_scalar_function, duckfn_entrypoint, DuckOptionResult};

/// ```sql
/// SELECT double_it(21);    -- 42
/// SELECT double_it(NULL);  -- NULL
/// SELECT double_it(13);    -- error: unlucky input
/// ```
#[duck_scalar_function]
pub fn double_it(v: Option<i64>) -> DuckOptionResult<i64> {
    if v == Some(13) {
        return Err(duck_error("unlucky input"));
    }
    Ok(v.map(|x| x * 2))
}

// Generate the extension entry point (name must be lowercase + underscores).
duckfn_entrypoint!("my_ext");

The wrapper, the logical types and the registration are all generated, so the snippet above is entirely safe Rust. The only place unsafe shows up is manual registration: #[duck_custom_register] calls quack-rs' unsafe fn register_scalar / register_aggregate / register_table.

Calling the generated module of a #[duck_scalar_function] exposes builders such as scalar_function_builder() and scalar_overload_builder(), so you can register overloads or function sets yourself.

Documentation

The full guide — every attribute and its arguments, the type mapping, the error model, and a runnable example extension — lives at https://shijianjs.github.io/duckfn/:

中文文档：https://shijianjs.github.io/duckfn/zh-Hans/

Rust API reference: https://docs.rs/duckfn

License

Licensed under the MIT License.