FAQ

Frequently asked questions about quack-rs and building DuckDB extensions in Rust.


General

What is quack-rs?

quack-rs is a Rust SDK for building DuckDB loadable extensions using DuckDB's pure C Extension API. It provides safe, ergonomic builders for registering scalar functions, aggregate functions, table functions, cast functions, replacement scans, SQL macros, and copy functions (via the duckdb-1-5 feature), along with helpers for reading and writing DuckDB vectors, and utilities for publishing community extensions.

Why does this exist?

Building a DuckDB extension in Rust means solving a set of undocumented FFI problems that each developer otherwise discovers independently. quack-rs documents all 38 known pitfalls, and its API prevents most of them. See the Pitfall Catalog.

What DuckDB version does quack-rs target?

quack-rs requires libduckdb-sys = ">=1.4.4, <1.20100" and, with the default features, supports DuckDB 1.4.4 through 2.0.x. An extension that uses a duckdb-1-5* feature loads into 1.5.6 and 2.0.0 only, and refuses a release quack-rs has not listed (see ABI Compatibility). Releases before 1.4.4 are not supported. The upper bound keeps out the DuckDB 2.1 bindings until a quack-rs release has been tested against them; see Installation. CI runs the test suite against DuckDB v1.4.4, v1.4.5, v1.5.0, v1.5.3, v1.5.4, v1.5.5, v1.5.6 and v2.0.0 (the last with the DuckDB 2.0 bindings, libduckdb-sys 1.20000.x), and loads a built extension into v1.4.4, v1.5.0, v1.5.5, v1.5.6, v2.0.0 and the latest release. DuckDB supports 2.0 (a long-term support release) until at least October 2027, 1.5 until March 2027 and 1.4 until late November 2026.

The C API version passed to the dispatch-table initializer is "v1.2.0", available as quack_rs::DUCKDB_API_VERSION. Every supported DuckDB release (1.4.4 and later) loads extensions built for it (1.5.6 and 2.0.x declare C API v1.5.6, but still accept v1.2.0). An extension that uses the duckdb-1-5* features is stamped C API v1.5.6 instead (quack_rs::DUCKDB_API_VERSION_1_5_6) and loads into DuckDB 1.5.6 and 2.0.0; the runtime guard refuses a release quack-rs has not listed (2.0.1, for now). The C API version is a separate identifier from the DuckDB release and from the libduckdb-sys crate version, which encodes DuckDB vMAJOR.MINOR.PATCH as 1.(10000·MAJOR + 100·MINOR + PATCH).N (e.g. 1.10505.0 for DuckDB 1.5.5, 1.20000.0 for 2.0.0).

What is the minimum supported Rust version (MSRV)?

Rust 1.86.0 or later. This is enforced in Cargo.toml with rust-version = "1.86.0".

Is quack-rs production-ready?

It is pre-1.0, and you should judge it against your own requirements; this page cannot give you a yes or a no. What the record shows:

  • The API still changes. Minor releases before 1.0 can break it; each one lists its breaking changes, with migration notes, in the changelog.
  • 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, process aborts and wrong answers, and found one serious defect in unreleased code before it was published: aggregate functions returned wrong results in release builds with Cargo's default profile. AUDIT.md in the repository records 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 the duckdb-1-5 features are used.
  • Some limits are DuckDB's. The C API has defects quack-rs can only document or work around; see Known Limitations.

It was extracted from duckdb-behavioral, a DuckDB community extension, where the first of the pitfalls it now documents were discovered. If you ship an extension built on it, run end-to-end tests that load the extension into each DuckDB release you support (see the Testing Guide).


Functions

Can I expose SQL macros as an extension?

Yes, without any C++ wrapper code. Use quack_rs::sql_macro::SqlMacro:

#![allow(unused)]
fn main() {
use libduckdb_sys::duckdb_connection;
fn demo(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
use quack_rs::sql_macro::SqlMacro;

// Scalar macro
let m = SqlMacro::scalar("double_it", &["x"], "x * 2")?;
unsafe { m.register(con) }?;

// Table macro
let m = SqlMacro::table("recent_events", &["n"],
    "SELECT * FROM events ORDER BY ts DESC LIMIT n")?;
unsafe { m.register(con) }?;
Ok(())
}
}

Register them in your registration closure (the one passed to entry_point! or init_extension) alongside your other functions. A table macro's body is bound when it is created, so the events table must already exist or register returns an error. See SQL Macros.

Can my extension read a file with std::fs?

It can, and it should not when the path comes from SQL. std::fs ignores DuckDB's enable_external_access and allowed_directories settings, so a function that reads a user-supplied path with it works around a restriction the person running DuckDB set (read_csv on the same path fails with a permission error). Open such paths with the FileSystem wrapper (feature duckdb-1-5); see Virtual File System.

Can I register multiple overloads of the same function?

Yes, using AggregateFunctionSetBuilder (for aggregates) or ScalarFunctionSetBuilder (for scalars). Both support complex parameter types via param_logical(LogicalType) and complex return types via returns_logical(LogicalType), and in both, each overload may return a different type — DuckDB resolves an overload from its parameter types and arity alone. See Overloading with Function Sets.

Can I register multiple functions in one extension?

Yes. The registration closure receives a duckdb_connection and can register as many functions as needed:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_connection, duckdb_extension_access, duckdb_extension_info};
use quack_rs::error::ExtensionError;
use quack_rs::sql_macro::SqlMacro;
use quack_rs::DUCKDB_API_VERSION;
unsafe fn register_word_count(_: duckdb_connection) -> Result<(), ExtensionError> { Ok(()) }
unsafe fn register_sentence_count(_: duckdb_connection) -> Result<(), ExtensionError> { Ok(()) }
unsafe fn demo(info: duckdb_extension_info, access: *const duckdb_extension_access) -> bool {
quack_rs::entry_point::init_extension(info, access, DUCKDB_API_VERSION, |con| {
    unsafe { register_word_count(con) }?;
    unsafe { register_sentence_count(con) }?;
    unsafe {
        SqlMacro::scalar("double_it", &["x"], "x * 2")?
            .register(con)?;
    }
    Ok(())
})
}
}

Can I use the duckdb crate instead of libduckdb-sys?

No. The duckdb crate's bundled feature embeds its own copy of DuckDB. A loadable extension must link against the DuckDB that loads it, not bundle a separate copy. Use libduckdb-sys with the loadable-extension feature.

Can I have a scalar function with no parameters?

Yes. Just do not call param:

#![allow(unused)]
fn main() {
use libduckdb_sys::{duckdb_connection, duckdb_data_chunk, duckdb_function_info, duckdb_vector};
use quack_rs::prelude::*;
unsafe extern "C" fn quack_callback(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
fn demo(con: duckdb_connection) -> Result<(), ExtensionError> {
unsafe {
    ScalarFunctionBuilder::new("current_quack")
        .returns(TypeId::Varchar)
        .function(quack_callback)
        .register(con)?;
}
Ok(())
}
}

Testing

Do I need a DuckDB instance to run unit tests?

No. AggregateTestHarness simulates the aggregate lifecycle in pure Rust without any DuckDB dependency. You can run cargo test without loading a DuckDB binary.

My unit tests all pass but the extension crashes. Why?

Unit tests cannot detect FFI wiring bugs. See Pitfall P3 and the Testing Guide. Always run end-to-end tests that load the packaged extension into a real DuckDB process.

How do I test SQL macros?

SqlMacro::to_sql() is pure Rust and requires no DuckDB connection:

#![allow(unused)]
fn main() {
use quack_rs::sql_macro::SqlMacro;
let m = SqlMacro::scalar("triple", &["x"], "x * 3").unwrap();
assert_eq!(m.to_sql(), r#"CREATE OR REPLACE MACRO "triple"("x") AS (x * 3)"#);
}

For an end-to-end test, call the macro from your SQLLogicTest file:

query I
SELECT double_it(21);
----
42

Publishing

How do I publish to the DuckDB community extensions registry?

  1. Scaffold your project with generate_scaffold
  2. Push to GitHub
  3. Submit a pull request to the community-extensions repo with your description.yml

See Community Extensions for the full workflow.

My extension name is taken. What should I do?

Use a vendor-prefixed name: myorg_analytics instead of analytics. Extension names must be unique among DuckDB community extensions; check community-extensions.duckdb.org before you pick one.

Do I need to set up CI manually?

No. generate_scaffold produces two workflows. extension-ci.yml builds, lints and tests the extension natively on Linux, macOS and Windows, and checks it builds on the minimum Rust version. MainDistributionPipeline.yml runs DuckDB's own extension-ci-tools distribution workflow — the one the community build uses — for every platform not listed in excluded_platforms (the scaffold excludes the WebAssembly and MinGW targets by default).

Can my extension be installed with INSTALL ... FROM community?

Yes, once your pull request is merged into the community-extensions repository. Until then, users load the .duckdb_extension file directly, starting DuckDB with -unsigned because a local build is not signed:

LOAD './path/to/my_extension.duckdb_extension';

Troubleshooting

My aggregate returns wrong results with no error.

The most common cause is Pitfall L1: your combine callback is not propagating all configuration fields. See Pitfall L1 and test with AggregateTestHarness::combine.

The NULLs my function writes come back as values.

You are likely calling duckdb_vector_get_validity without first calling duckdb_vector_ensure_validity_writable. A vector that has never held a NULL has no validity mask, so duckdb_vector_get_validity returns a null pointer and duckdb_validity_set_row_invalid silently does nothing (dereferencing that pointer yourself crashes). Use VectorWriter::set_null instead. See Pitfall L4.

My function is not found in SQL after LOAD.

If LOAD succeeded, the entry point ran, so check the name you gave the builder. If you build a function set through the raw C API instead of quack-rs's set builders, every member needs its own name, or DuckDB silently skips it (Pitfall L6).

If LOAD itself fails, check the entry point symbol. DuckDB takes the file's base name, lowercases it and calls <base name>_init_c_api, so my_extension.duckdb_extension needs my_extension_init_c_api (Pitfall P1).

LOAD fails before any of my code runs. What does the message mean?

DuckDB checks the file before it calls your entry point. The messages below are DuckDB's own, identical on 1.5.6 and 2.0.0 (captured from both CLIs):

DuckDB says (abridged)CauseFix
The file is not a DuckDB extension. The metadata at the end of the file is invalidA plain .so/.dylib/.dll renamed to .duckdb_extension: no footer.Run append_metadata on the library.
DuckDB extensions are files ending with '.duckdb_extension'LOAD was given the library itself.LOAD the stamped .duckdb_extension file.
did not contain function "<name>_init_c_api" … undefined symbolThe file's base name is not the name the library exports its entry point under (Pitfall P1). append_metadata warns about this when it stamps.Name the output <name>.duckdb_extension, with <name> the one the library exports <name>_init_c_api for.
The file was built for the platform 'osx_arm64', but we can only load extensions built for platform 'linux_amd64'Stamped with another --platform, or built on another OS.Stamp with the platform of the machine that will load it (the default).
could not be loaded because its signature is either missing or invalid and unsigned extensions are disabled by configurationA locally built extension is unsigned.Start the CLI with -unsigned, or set allow_unsigned_extensions when opening the database.
The file was built specifically for DuckDB version 'v1.5.6' and can only be loaded with that version of DuckDBStamped C_STRUCT_UNSTABLE, which pins the exact release. DuckDB 2.0 loads that ABI type only through a C API v2 entry point, which quack-rs does not generate.Stamp C_STRUCT with v1.2.0 (or v1.5.6 for the duckdb-1-5* features).

Two more come from quack-rs's own checks, after DuckDB has accepted the file: layout mismatch … slots (the extension was compiled against a C API layout the running engine does not have; see ABI compatibility) and the unknown engine refusal for a release newer than the table in abi.rs.

make configure fails with a missing file error.

The extension-ci-tools submodule is missing. In a new project, such as one fresh from the scaffold, add it once (git submodule update --init does nothing until it has been added). The scaffold's Makefile error names the branch; for a C_STRUCT build it is v2.0-cyanoptera, the branch for DuckDB 2.0 (extension-ci-tools has no v2.0.0 branch):

git submodule add -b v2.0-cyanoptera https://github.com/duckdb/extension-ci-tools.git extension-ci-tools

A C_STRUCT_UNSTABLE build pinned to a 1.x release uses that release's branch instead, such as -b v1.5.5.

In a clone of a repository that already has the submodule:

git submodule update --init --recursive

See Pitfall P4.

My SQLLogicTest fails in CI but passes locally.

SQLLogicTest does exact string matching. The most common issue is a difference in NULL representation, decimal places, or line endings. Run the query in the same DuckDB version used by CI and copy the output verbatim.

How do I read a VARCHAR that is longer than 12 bytes?

VectorReader::read_str handles both the inline (≤ 12 bytes) and pointer (> 12 bytes) formats automatically. No special handling needed.

What happens if I read from a NULL row?

You get garbage data from the vector's data buffer — and for VARCHAR or BLOB, possibly a stale pointer into freed memory. Always check is_valid before reading. See NULL Handling & Strings.


Architecture

Why use libduckdb-sys with loadable-extension instead of the duckdb crate?

The duckdb crate is designed for embedding DuckDB, not for extending it. Its bundled feature includes a statically linked DuckDB binary, which conflicts with the DuckDB runtime that loads your extension. libduckdb-sys with loadable-extension provides lazy-initialized function pointers that are populated by DuckDB at extension load time.

Why not use duckdb-loadable-macros?

Use it when it fits. As of duckdb and duckdb-loadable-macros 1.20000.1 the macro opens a duckdb::Connection from the raw database (duckdb::Connection::open_from_raw) and reports errors through the API's set_error; an earlier release of the macro depended on extract_raw_connection and the duckdb crate's internal layout, which crashed when the layout changed, and that history is why init_extension calls the C API entry sequence directly. What differs now is coverage and compatibility: the duckdb crate's loadable-extension path wraps scalar (vscalar) and table (vtab) functions only, while quack-rs also wraps aggregate, cast, copy and replacement-scan functions and SQL macros, guards every callback it generates against panics, and stays on the stable C API v1, whose binaries load across DuckDB releases. See the README's comparison.

Why must the release profile use panic = "unwind"?

quack-rs wraps every entry point and every callback it generates in catch_unwind and reports a panic as an ordinary SQL error (a raw extern "C" callback you write yourself needs a *_callback! macro or catch_ffi_panic; see Installation). catch_unwind cannot catch anything under panic = "abort": the process terminates at the panic site, taking the user's DuckDB session with it. validate_release_profile rejects abort for this reason. Returning Result and using ? is still the right style — the guards are a safety net, not a substitute.

Can I use async Rust in my extension?

Not directly in FFI callbacks. DuckDB's callbacks are synchronous C functions. You can run an async runtime such as Tokio and block on async tasks inside callbacks (for example with Runtime::block_on), but the callbacks themselves must return synchronously.

How does FfiState<T> prevent double-free?

Each state slot starts with a tag that init_callback writes once the T is in place. destroy_callback drops the T (freeing its box, when T is too large to store inline) only when the tag matches, and clears the tag first. A second call to destroy_callback on the same state finds no tag and does nothing.